home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
L' Effet Pommier 3
/
L'Effet Pommier - Volume 03.iso
/
Graphismes
/
3D
/
POV-Ray 3.0B5a PPC
/
POV-Ray 3.0B5a
/
POVDOC.Documentation
/
POVRAY.DOC
< prev
Wrap
Text File
|
1996-02-19
|
507KB
|
11,922 lines
Persistence of Vision(tm) Ray Tracer
(POV-Ray(tm))
Reference Guide Version 3.0.6b
Copyright 1996 POV-Team(tm)
1 Introduction
2 POV-Ray Options
2.1 Setting POV-Ray Options
2.1.1 Command Line Switches
2.1.2 Using INI Files
2.1.3 Using the POVINI Environment Variable
2.2 Options Reference
2.2.1 Animation Options
2.2.1.1 External Animation Loop
2.2.1.2 Internal Animation Loop
2.2.1.3 Subsets of Animation Frames
2.2.1.4 Cyclic Animation
2.2.1.5 Field Rendering
2.2.2 Output Options
2.2.2.1 General Output Options
2.2.2.1.1 Height and Width of Output
2.2.2.1.2 Partial Output Options
2.2.2.1.3 Interrupting Options
2.2.2.1.4 Resuming Options
2.2.2.2 Display Output Options
2.2.2.2.1 Display Hardware Settings
2.2.2.2.2 Display Related Settings
2.2.2.2.3 Mosaic Preview
2.2.2.3 File Output Options
2.2.2.3.1 Output File Type
2.2.2.3.2 Output File Name
2.2.2.3.3 Output File Buffer
2.2.2.4 CPU Utilization Histogram
2.2.2.4.1 File Type
2.2.2.4.2 File Name
2.2.2.4.3 Grid Size
2.2.3 Scene Parsing Options
2.2.3.1 Input File Name
2.2.3.2 Library Paths
2.2.3.3 Language Version
2.2.3.4 Removing User Bounding
2.2.4 Shell-out to Operating System
2.2.4.1 String Substitution in Shell Commands
2.2.4.2 Shell Command Sequencing
2.2.4.3 Shell Command Return Actions
2.2.5 Text Output
2.2.5.1 Text Streams
2.2.5.2 Console Text Output
2.2.5.3 Directing Text Streams to Files
2.2.5.4 Help Screen Switches
2.2.6 Tracing Options
2.2.6.1 Quality Settings
2.2.6.2 Automatic Bounding Control
2.2.6.3 Anti-Aliasing Options
3 Scene Description Language
3.1 Language Basics
3.1.1 Identifiers and Keywords
3.1.2 Comments
3.1.3 Float Expressions
3.1.3.1 Float Literals
3.1.3.2 Float Identifiers
3.1.3.3 Float Operators
3.1.4 Vector Expressions
3.1.4.1 Vector Literals
3.1.4.2 Vector Identifiers
3.1.4.3 Vector Operators
3.1.4.4 Operator Promotion
3.1.5 Specifying Colors
3.1.5.1 Color Vectors
3.1.5.2 Color Keywords
3.1.5.3 Color Identifiers
3.1.5.4 Color Operators
3.1.5.5 Common Color Pitfalls
3.1.6 Strings
3.1.6.1 String Literals
3.1.6.2 String Identifiers
3.1.7 Built-in Identifiers
3.1.7.1 Constant Built-in Identifiers
3.1.7.2 Built-in Identifier 'clock'
3.1.7.3 Built-in Identifier 'version'
3.1.8 Functions
3.1.8.1 Float Functions
3.1.8.2 Vector Functions
3.1.8.3 String Functions
3.2 Language Directives
3.2.1 Include Files
3.2.2 Declare
3.2.2.1 Declaring identifiers
3.2.3 Default Directive
3.2.4 Version Directive
3.2.5 Conditional Directives
3.2.5.1 IF ELSE Directives
3.2.5.2 IFDEF Directives
3.2.5.3 SWITCH CASE & RANGE Directives
3.2.5.4 WHILE Directive
3.2.6 User Message Directives
3.2.6.1 Text Message Streams
3.2.6.2 Text Formatting
3.3 POV-Ray Coordinate System
3.3.1 Transformations
3.3.1.1 Translate
3.3.1.2 Scale
3.3.1.3 Rotate
3.3.1.4 Matrix Keyword
3.3.2 Transformation Order
3.3.3 Transform Identifiers
3.3.4 Transforming Textures and Objects
3.4 Camera
3.4.1 Type of Projection
3.4.2 Focal Blur
3.4.3 Camera Ray Perturbation
3.4.4 Placing the Camera
3.4.4.1 Location and Look_At
3.4.4.2 The Sky Vector
3.4.4.3 The Direction Vector
3.4.4.4 Up and Right Vectors
3.4.4.4.1 Aspect Ratio
3.4.4.4.2 Handedness
3.4.4.5 Transforming the Camera
3.4.5 Camera Identifiers
3.5 Objects
3.5.1 Finite Solid Primitives
3.5.1.1 Blob
3.5.1.2 Box
3.5.1.3 Cone
3.5.1.4 Cylinder
3.5.1.5 Height Field
3.5.1.6 Julia Fractal
3.5.1.7 Lathe
3.5.1.8 Prism
3.5.1.9 Sphere
3.5.1.10 Superquadric Ellipsoid
3.5.1.11 Surface of Revolution
3.5.1.12 Text
3.5.1.13 Torus
3.5.2 Finite Patch Primitives
3.5.2.1 Bicubic patch
3.5.2.2 Disc
3.5.2.3 Mesh
3.5.2.4 Polygon
3.5.2.5 Triangle and smooth triangle
3.5.3 Infinite Solid Primitives
3.5.3.1 Plane
3.5.3.2 Poly, Cubic and Quartic
3.5.3.3 Quadric
3.5.4 Constructive Solid Geometry
3.5.4.1 About CSG
3.5.4.2 Inside and Outside
3.5.4.3 Union
3.5.4.4 Intersection
3.5.4.5 Difference
3.5.4.6 Merge
3.5.5 Light Sources
3.5.5.1 Point Lights
3.5.5.2 Spotlights
3.5.5.3 Cylindrical Lights
3.5.5.4 Area Lights
3.5.5.5 Shadowless
3.5.5.6 Looks_like
3.5.5.7 Light Fading
3.5.5.8 Atmospheric Attenuation
3.5.6 Object Modifiers
3.5.6.1 Clipped_By
3.5.6.2 Bounded_By
3.5.6.3 Hollow
3.5.6.4 No_Shadow
3.6 Textures
3.6.1 Pigment
3.6.1.1 Solid Color Pigments
3.6.1.2 Color List Pigments
3.6.1.3 Color Maps
3.6.1.4 Pigment Maps
3.6.1.5 Image Maps
3.6.1.5.1 Specifying an Image Map
3.6.1.5.2 The map_type Option
3.6.1.5.3 The Filter and Transmit Bitmap Modifiers
3.6.1.5.4 Using the Alpha Channel
3.6.1.6 Quick Color
3.6.2 Normal
3.6.2.1 Slope Maps
3.6.2.2 Normal Maps
3.6.2.3 Bump Maps
3.6.2.3.1 Specifying a Bump Map
3.6.2.3.2 Bump_Size
3.6.2.3.3 Use_Index and Use_Color
3.6.3 Finish
3.6.3.1 Ambient
3.6.3.2 Diffuse Reflection Items
3.6.3.2.1 Diffuse
3.6.3.2.2 Brilliance
3.6.3.2.3 Crand Graininess
3.6.3.3 Highlights
3.6.3.3.1 Phong Highlights
3.6.3.3.2 Specular Highlight
3.6.3.3.3 Metallic Highlight Modifier
3.6.3.4 Specular Reflection
3.6.3.5 Refraction
3.6.3.5.1 Light Attenuation
3.6.3.5.2 Faked Caustics
3.6.3.6 Iridescence
3.6.4 Halo
3.6.4.1 Halo Type
3.6.4.1.1 Attenuating
3.6.4.1.2 Dust
3.6.4.1.3 Emitting
3.6.4.1.4 Glowing
3.6.4.2 Density Mapping
3.6.4.2.1 Box Mapping
3.6.4.2.2 Cylindrical Mapping
3.6.4.2.3 Planar Mapping
3.6.4.2.4 Spherical Mapping
3.6.4.3 Density Function
3.6.4.3.1 Constant
3.6.4.3.2 Linear
3.6.4.3.3 Cubic
3.6.4.3.4 Poly
3.6.4.4 Halo Color Map
3.6.4.5 Halo Sampling
3.6.4.5.1 Number of Samples
3.6.4.5.2 Supersampling
3.6.4.5.3 Jitter
3.6.4.6 Halo Modifiers
3.6.4.6.1 Turbulence Modifier
3.6.4.6.2 Octaves Modifier
3.6.4.6.3 Omega Modifier
3.6.4.6.4 Lambda Modifier
3.6.4.6.5 Frequency Modifier
3.6.4.6.6 Phase Modifier
3.6.4.6.7 Transformation Modifiers
3.6.5 Special Textures
3.6.5.1 Tiles
3.6.5.2 Material Maps
3.6.5.2.1 Specifying a Material Map
3.6.6 Layered Textures
3.6.7 Patterns
3.6.7.1 Agate
3.6.7.2 Average
3.6.7.3 Bozo
3.6.7.4 Brick
3.6.7.5 Bumps
3.6.7.6 Checker
3.6.7.7 Crackle
3.6.7.8 Dents
3.6.7.9 Gradient
3.6.7.10 Granite
3.6.7.11 Hexagon
3.6.7.12 Leopard
3.6.7.13 Mandel
3.6.7.14 Marble
3.6.7.15 Onion
3.6.7.16 Quilted
3.6.7.17 Radial
3.6.7.18 Ripples
3.6.7.19 Spiral1
3.6.7.20 Spiral2
3.6.7.21 Spotted
3.6.7.22 Waves
3.6.7.23 Wood
3.6.7.24 Wrinkles
3.6.8 Pattern Modifiers
3.6.8.1 Transforming Patterns
3.6.8.2 Frequency and Phase
3.6.8.3 Waveform
3.6.8.4 Turbulence
3.6.8.5 Octaves
3.6.8.6 Lambda
3.6.8.7 Omega
3.6.8.8 Warps
3.6.8.8.1 Black Hole Warp
3.6.8.8.2 Repeat Warp
3.6.8.8.3 Turbulence Warp
3.6.8.9 Bitmap modifiers
3.6.8.9.1 The once Option
3.6.8.9.2 The "map_type" Option
3.6.8.9.3 The interpolate Option
3.7 Atmospheric Effects
3.7.1 Atmosphere
3.7.2 Background
3.7.3 Fog
3.7.4 Sky Sphere
3.7.5 Rainbow
3.8 Miscellaneous Features
3.8.1 Ambient Light
3.9 Global Settings
3.9.1 ADC_Bailout
3.9.2 Ambient Light
3.9.3 Assumed_Gamma
3.9.3.1 Monitor Gamma
3.9.3.2 Image File Gamma
3.9.3.3 Scene File Gamma
3.9.4 HF_Gray_16
3.9.5 Irid_Wavelength
3.9.6 Max_Trace_Level
3.9.7 Max_Intersections
3.9.8 Number_Of_Waves
3.9.9 Radiosity
3.9.9.1 How Radiosity Works
3.9.9.2 Adjusting Radiosity
3.9.9.2.1 brightness
3.9.9.2.2 count
3.9.9.2.3 distance_maximum
3.9.9.2.4 error_bound
3.9.9.2.5 gray_threshold
3.9.9.2.6 low_error_factor
3.9.9.2.7 minimum_reuse
3.9.9.2.8 nearest_count
3.9.9.2.9 radiosity_quality
3.9.9.2.10 recursion_limit
3.9.9.3 Tips on Radiosity
*** APPENDICES ***
A POV-Ray Output Messages
A.1 Options in Use
A.2 Warning Messages
A.2.1 Warnings during the Parsing Stage
A.2.2 Other Warnings
A.3 Error Messages
A.3.1 Scene File Errors
A.3.2 Other Errors
A.4 Statistics
B Help on Help
C Frequently Asked Questions
D Where to Get More POV-Ray Stuff
E Copyright
F Authors
1 Introduction
This reference guide describes all command line options and INI file
switches, the scene description language and all other features that are part
of POV-Ray. It is supposed to be used as a reference for looking things up.
It does not contain detailed explanations on how scenes are written or how
POV-Ray is used. It just explains all features, their syntax, applications,
limits, drawbacks, etc.
A seperate User Guide will describe how POV-Ray is installed and started. It
will also have a tutorial section that will explain how to create own scenes,
how to use most of the special features, etc. At this time the User Guide may
not be available because we just weren't able to finish.
2 POV-Ray Options
POV-Ray was originally created as a command-line program for operating
systems without graphical interfaces, dialog boxes and pull-down menus. Most
versions of POV-Ray still use command-line switches to tell it what to do.
This documentation assumes you are using the command-line version. If you are
using Macintosh, MS-Windows or other GUI versions, there will be dialog boxes
or menus which do the same thing. There is system-specific documentation for
each system describing the specific commands.
2.1 Setting POV-Ray Options
There are two distinct ways of setting POV-Ray options: command line switches
and INI file keywords. Both are explained in detail in the following
sections.
2.1.1 Command Line Switches
Command line switches consist of a + (plus) or - (minus) sign, followed by
one or more alphabetic characters and possibly a numeric value. Here is a
typical command line with switches.
POVRAY +Isimple.pov +V +W80 +H60
POVRAY is the name of the program and it is followed by several switches.
Each switch begins with a plus or minus sign. The +I switch with the filename
tells POV-Ray what scene file it should use as input and +V tells the program
to output its status to the text screen as it's working. The +W and +H
switches set the width and height of the image in pixels. This image will be
80 pixels wide by 60 pixels high.
In switches which toggle a feature, the plus turns it on and minus turns it
off. For example +P turns on the "pause for keypress when finished" option
while -P turns it off. Other switches are used to specify values and do not
toggle a feature. Either plus or minus may be used in that instance. For
example +W320 sets the width to 320 pixels. You could also use -W320 and get
the same results.
Switches may be specified in upper or lower case. They are read left to right
but in general may be specified in any order. If you specify a switch more
than once, the previous value is generally overwritten with the last
specification. The only exception is the +L switch for setting library paths.
Up to ten unique paths may be specified.
Almost all +/- switches have an equivalent option which can be used in an INI
file which is described in the next section. A detailed description of each
switch is given in the option reference section.
2.1.2 Using INI Files
Because it is difficult to set more than a few options on a command line, you
have the ability to put multiple options in one or more text files. These
initialization files or INI files have .INI as their default extension.
Previous versions of POV-Ray called them default files or DEF files. You may
still use existing DEF files with this version of POV-Ray.
The majority of options you use will be stored in INI files. The command line
switches are recommended for options which you will turn off or on frequently
as you perform test renderings of a scene you are developing. The file
POVRAY.INI is automatically read if present. You may specify additional INI
files on the command-line by simply typing the file name on the command line.
For example:
POVRAY MYOPTS.INI
If no extension is given, then .ini is assumed. POV-Ray knows this is not a
switch because it is not preceded by a plus or minus. In fact a common error
among new users is they forget to put the +I switch before the input file
name. Without the switch, POV-Ray thinks that the scene file simple.pov is an
INI file. Don't forget! If no plus or minus precedes a command line switch,
it is assumed to be an INI file name.
You may have multiple INI files on the command line along with switches. For
example:
POVRAY MYOPTS +V OTHER
This reads options from MYOPTS.INI, then sets the +V switch, then reads
options from OTHER.INI.
An INI file is a plain ASCII text file with options of the form...
Option_keyword=VALUE ; Text after semicolon is a comment
For example the INI equivalent of the switch +Isimple.pov is..
Input_File_Name=simple.pov
Options are read top to bottom in the file but in general may be specified in
any order. If you specify an option more than once, the previous values are
generally overwritten with the last specification. The only exception is the
Library_Path=PATH options. Up to ten unique paths may be specified.
Almost all INI-style options have equivalent +/- switches. The option
reference section gives a detailed description of all POV-Ray options. It
includes both the INI-style settings and the +/- switches.
The INI keywords are not case sensitive. Only one INI option is permitted per
line of text. You may also include switches in your INI file if they are
easier for you. You may have multiple switches per line but you should not
mix switches and INI options on the same line. You may nest INI files by
simply putting the file name on a line by itself with no equals sign after
it. Nesting may occur up to ten levels deep.
For example:
; This is a sample INI file. This entire line is a comment.
; Blank lines are permitted.
Input_File_Name=simple.pov ;This sets the input file name
+W80 +H60 ; Traditional +/- switches are permitted too
MOREOPT ; Read MOREOPT.INI and continue with next line
+V ; Another switch
; That's all folks!
INI files may have labeled sections so that more than one set of options may
be stored in a single file. Each section begins with a label in [] brackets.
For example:
; RES.INI
; This sample INI file is used to set resolution.
+W120 +H100 ; This section has no label.
; Select it with "RES"
[Low]
+W80 +H60 ; This section has a label.
; Select it with "RES[Low]"
[Med]
+W320 +H200 ; This section has a label.
; Select it with "RES[Med]"
[High]
+W640 +H480 ; Labels are not case sensitive.
; "RES[high]" works
[Really High]
+W800 +H600 ; Labels may contain blanks
When you specify the INI file you should follow it with the section label in
brackets. For example...
POVRAY RES[Med] +Imyfile.pov
POV-Ray reads RES.INI and skips all options until it find the label [Med]. It
processes options after that label until it finds another label and then it
skips. If no label is specified on the command line then only the unlabeled
area at the top of the file is read. If a label is specified, the unlabeled
area is ignored.
2.1.3 Using the POVINI Environment Variable
The environment variable POVINI is used to specify the location and name of a
default INI file that is read every time POV-Ray is executed. If POVINI is
not specified a default INI file may be read depending on the platform used.
If the specified file does not exist a warning message is printed.
To set the environment variable under MS-DOS you might put the following line
in your AUTOEXEC.BAT file...
set POVINI=c:\povray3\default.ini
On most operating systems the sequence of reading options is as follows:
1. Read options from default INI file specified by the POVINI environment
variable or platform specific INI file.
2. Read switches from command line (this includes reading any specified
INI/DEF files).
The POVRAYOPT environment variable supported by previous POV-Ray versions is
no longer available.
2.2 Options Reference
As explained in the previous section, options may be specified by switches or
INI-style options. Almost all INI-style options have equivalent +/- switches
and most switches have equivalent INI-style option. The following sections
give a detailed description of each POV-Ray option. It includes both the
INI-style settings and the +/- switches.
The notation and terminology used is described in the tables below.
Keyword=bool turn Keyword on if bool equals true, yes, on or 1 and turn it
off if it is any other value.
Keyword=true do this option if true, yes, on or 1 is specified.
Keyword=false do this option if false, no, off or 0 is specified.
Keyword=file any valid file name. Note: some options prohibit the use of
any of the above true or false values as a file name. They
are noted in later sections.
n any integer such as +w320
n.n any float such as Clock=3.45
0.n any float < 1.0 even if it has no leading 0
s any string of text
xor y any single character
path any directory name, drive optional, no final path separator ("\" or
"/", depending on the operating system)
Unless otherwise specifically noted, you may assume that either a plus or
minus sign before a switch will produce the same results.
2.2.1 Animation Options
POV-Ray 3.0 greatly improved its animation capability with the addition of an
internal animation loop, automatic output file name numbering and the ability
to shell out to the operating system to external utilities which can assemble
individual frames into an animation. The internal animation loop is simple
yet flexible. You may still use external programs or batch files to create
animations without the internal loop as you may have done in POV-Ray 2.
2.2.1.1 External Animation Loop
Clock=n.n Sets "clock" float identifier to n.n
+Kn.n Same as Clock=n.n
The Clock=nn.nnn option or the +Knn.nnn switch may be used to pass a single
float value to the program for basic animation. The value is stored in the
float identifier clock. If an object had a rotate <0,clock,0> attached then
you could rotate the object by different amounts over different frames by
setting +K10.0, +K20.0... etc. on successive renderings. It is up to the user
to repeatedly invoke POV-Ray with a different Clock= value and a different
Output_File_Name= for each frame.
2.2.1.2 Internal Animation Loop
Initial_Frame=n Sets initial frame number to n
Final_Frame=n Sets final frame number
Initial_Clock=n.n Sets initial clock value
Final_Clock=n.n Sets final clock value
+KFIn Same as Initial_Frame=n
+KFFn Same as Final_Frame=n
+KIn.n Same as Initial_Clock=n.n
+KFn.n Same as Final_Clock=n.n
The internal animation loop new to POV-Ray 3.0 relieves the user of the task
of generating complicated sets of batch files to invoke POV-Ray multiple
times with different settings. While the multitude of options may look
intimidating, the clever set of defaults values means that you will probably
only need to specify the Final_Frame=nnn option or the +KFFnnn to specify the
number of frames. All other values may remain at their defaults.
Any Final_Frame setting other than -1 will trigger POV-Ray's internal
animation loop. For example Final_Frame=10 or +KFF10 causes POV-Ray to render
your scene 10 times. If you specified Output_File_Name=FILE.TGA then each
frame would be output as FILE01.TGA, FILE02.TGA, FILE03.TGA etc. The number
of zero-padded digits in the file name depends upon the final frame number.
For example +KFF100 would generate FILE001.TGA through FILE100.TGA. The frame
number may encroach upon the file name. On MS-DOS with an 8 character limit,
MYSCENE.POV would render to MYSCE001.TGA through MYSCE100.TGA.
The default Initial_Frame=1 will probably never have to be changed. You would
only change it if you were assembling a long animation sequence in pieces.
One scene might run from frame 1 to 50 and the next from 51 to 100. The
Initial_Frame=nnn or +KFInnn option is for this purpose.
Note that if you wish to render a subset of frames such as 30 through 40 out
of a 1 to 100 animation, you should not change Frame_Initial or Frame_Final.
Instead you should use the subset commands described in Subsets of Animation
Frames .
Unlike some animation packages, the action in POV-Ray animated scenes does
not depend upon the integer frame numbers. Rather you should design your
scenes based upon the float identifier clock. By default, the clock value is
0.0 for the initial frame and 1.0 for the final frame. All other frames are
interpolated between these values. For example if your object is supposed to
rotate one full turn over the course of the animation, you could specify
rotate 360*clock*y Then as clock runs from 0.0 to 1.0, the object rotates
about the y-axis from 0 to 360 degrees.
The major advantage to this system is that you can render a 10 frame
animation or a 100 frame or 500 frame or 329 frame animation yet you still
get one full 360 degree rotation. Test renders of a few frames work exactly
like final renders of many frames.
In effect you define the motion over a continuous float valued parameter (the
clock) and you take discrete samples at some fixed intervals (the frames). If
you take a movie or video tape a real scene it works the same way. An
object's actual motion depends only on time. It does not depend on the frame
rate of your camera.
Many users have already created scenes for POV-Ray 2 that expect clock values
over a range other than the default 0.0 to 1.0. For this reason we provide
the Initial_Clock=nn.nnn or +KInn.nnn and Final_Clock=nn.nnn or +KFnn.nnn
options. For example to run the clock from 25.0 to 75.0 you would specify
Initial_Clock=25.0 and Final_Clock=75.0. Then the clock would be set to 25.0
for the initial frame and 75.0 for the final frame. In between frames would
have clock values interpolated from 25.0 through 75.0 proportionally.
Users who are accustomed to using frame numbers rather than clock values
could specify Initial_Clock=1.0 and Final_Clock=10.0 and Frame_Final=10 for a
10 frame animation.
For new scenes, we recommend you do not change the Initial_Clock or
Final_Clock from their default 0.0 to 1.0 values. If you want the clock to
vary over a different range than the default 0.0 to 1.0, we recommend you
handle this inside your scene file as follows...
#declare Start = 25.0
#declare End = 75.0
#declare My_Clock = Start+(End-Start)*clock
Then use My_Clock in the scene description. This keeps the critical values
25.0 and 75.0 in your .POV file.
Note that more details concerning the inner workings of the animation loop
are in the section on shell-out operating system commands in "Shell-out to
Operating System" .
2.2.1.3 Subsets of Animation Frames
Subset_Start_Frame=n Set subset starting frame to n
Subset_Start_Frame=0.n Set subset starting frame to n percent
Subset_End_Frame=n Set subset ending frame to n
Subset_End_Frame=0.n Set subset ending frame to n percent
+SFn or +SF0.n Same as Subset_Start_Frame
+EFn or +EF0.n Same as Subset_End_Frame
When creating a long animation, it may be handy to render only a portion of
the animation to see what it looks like. Suppose you have 100 frames but only
want to test render 30 through 40. If you set Initial_Frame=30 and
Final_Frame=40 then the clock would vary from 0.0 to 1.0 from frames 30
through 40 rather than 0.30 through 0.40 as it should. Therefore you should
leave Initial_Frame=1 and Final_Frame=100 and use Subset_Start_Frame=30 and
Subset_End_Frame=40 to selectively render part of the scene. POV-Ray will
then properly compute the clock values.
Usually you will specify the subset using the actual integer frame numbers
however an alternate form of the subset commands takes a float value in the
range, 0.0 <= n.nnn < 1.0 which is interpreted as a fraction of the whole
animation. For example, Subset_Start_Frame=0.333 and Subset_End_Frame=0.667
would render the middle 1/3rd of a sequence regardless of the number of
frames.
2.2.1.4 Cyclic Animation
Cyclic_Animation=bool Turn cyclic animation on/off
+KC Turn cyclic animation on
-KC Turn cyclic animation off
Many computer animation sequences are designed to be run in a continuous
loop. Suppose you have an object that rotates exactly 360 degrees over the
course of your animation and you did rotate 360*clock*y to do so. Both the
first and last frames would be identical. Upon playback there would be a
brief one frame jerkiness. To eliminate this problem you need adjust the
clock so that the last frame does not match the first. For example a ten
frame cyclic animation should not use clock 0.0 to 1.0. It should run from
0.0 to 0.9 in 0.1 increments. However if you change to 20 frames it should
run from 0.0 to 0.95 in 0.05 increments. This complicates things because you
would have to change the final clock value every time you changed
Final_Frame. Setting the Cyclic_Animation=On option or the +KC will cause
POV-Ray to automatically adjust the final clock value for cyclic animation
regardless of how many total frames. The default value for this setting is
off.
2.2.1.5 Field Rendering
Field_Render=bool Turn field rendering on/off
Odd_Field=bool Set odd field flag
+UF Turn field rendering on
-UF Turn field rendering off
+UO Set odd field flag on
-UO Set odd field flag off
Field rendering is sometimes used for animations when the animation is being
output for television. TVs only display alternate scan lines on each vertical
refresh. When each frame is being displayed the fields are interlaced to give
the impression of a higher resolution image. The even scan lines make up the
even field, and are drawn first (i.e. scan lines 0, 2, 4, etc), followed by
the odd field, made up of the odd numbered scan lines are drawn afterwards.
If objects in an animation are moving quickly, their position can change
noticably from one field to the next. As a result, it may be desirable in
these cases to have POV-Ray render alternate fields at the actual field rate
(which is twice the frame rate), rather than rendering full frames at the
normal frame rate. This would save a great deal of time compared to rendering
the entire animation at twice the frame rate, and then only using half of
each frame.
By default, field rendering is not used. Setting Field_Render=on or using +UF
will cause alternate frames in an animation to be only the even or odd fields
of an animation. By default, the first frame is the even field, followed by
the odd field. You can have POV-Ray render the odd field first by specifying
Odd_Field=on, or by using the +UO switch.
2.2.2 Output Options
2.2.2.1 General Output Options
2.2.2.1.1 Height and Width of Output
Height=n Set screen height to n
Width=n Sets screen width to n pixels.
+Hn Same as Height=n (when n > 8)
+Wn Same as Width=n
These switches set the height and width of the image in pixels. This
specifies the image size for file output. The preview display, if on, will
generally attempt to pick a video mode to accommodate this size but the
display settings do not in any way affect the resulting file output.
2.2.2.1.2 Partial Output Options
Start_Column=n Set first column to n
Start_Column=0.n Set first column to n percent of width
+SCn or +SC0.n Same as Start_Column
Start_Row=n Set first row to n pixels
Start_Row=0.n Set first row to n percent of height
+SRn or +Sn Same as Start_Row=n
+SR0.n or +S0.n Same as Start_Row=0.n
End_Column=n Set last column to n pixels
End_Column=0.n Set last column to n percent of width
+ECn or +EC0.n Same as End_Column
End_Row=n Set last row to n pixels
End_Row=0.n Set last row to n percent of height
+ERn or +En Same as End_Row=n
+ER0.n or +E0.n Same as End_Row=0.n
When doing test rendering it is often convenient to define a small,
rectangular sub-section of the whole screen so you can quickly check out one
area of the image. The Start_Row, End_Row, Start_Column and End_Column
options allow you to define the subset area to be rendered. The default
values are the full size of the image from (1,1) which is the upper left to
(w,h) on the lower right where w and h are the Width=nnn and Height=nnn
values you have set.
Note if the number specified is greater than 1 then it is interpreted as an
absolute row or column number in pixels. If it is a decimal value between 0.0
and 1.0 then it is interpreted as a percent of the total width or height of
the image. For example: Start_Row=0.75 and Start_Column=0.75 starts on a row
75% down from the top at a column 75% from the left. Thus it renders only the
lower-right 25% of the image regardless of the specified width and height.
The +SR, +ER, +SC and +EC switches work the same as the corresponding
INI-style settings for both absolute settings or percentages. Early versions
of POV-Ray allowed only start and end rows to be specified with +Snnn and
+Ennn so they are still supported in addition to +SR and +ER.
2.2.2.1.3 Interrupting Options
Test_Abort=bool Turn test for user abort on/off
+X Turn test abort on
-X Turn test abort off
Test_Abort_Count=n Set to test for abort every n pixels
+Xn Set to test for abort every n pixels on
-Xn Set to test for abort off (in future test every n
pixels)
On some operating systems once you start a rendering you must let it finish.
The Test_Abort=on option or +X switch causes POV-Ray to test the keyboard for
keypress. If you have pressed a key, it will generate a controlled user
abort. Files will be flushed and closed but only data through the last full
row of pixels is saved. POV-Ray exits with an error code 2. (Normally POV-Ray
returns 0 for a successful run or 1 for a fatal error.)
When this option is on, the keyboard is polled on every line while parsing
the scene file and on every pixel while rendering. Because polling the
keyboard can slow down a rendering, the Test_Abort_Count=nnn option or +Xnnn
switch causes the test to be performed only every nnn pixels rendered or
scene lines parsed.
2.2.2.1.4 Resuming Options
Continue_Trace=bool Sets continued trace on/off
+C Sets continued trace on
-C Sets continued trace off
Create_Ini=file Generate an INI file to file
Create_Ini=true Generate file.ini where file is scene name.
Create_Ini=false Turn off generation of previously set file.ini
+GIsss Same as Create_Ini=sss
If you abort a render while it's in progress or if you used the End_Row
option to end the render prematurely, you can use Continue_Trace=on or
{/HIW}+C option to continue the render later at the point where you left off.
This option reads in the previously generated output file, displays the
partial image rendered so far, then proceeds with the ray tracing. This
option cannot be used if file output is disabled with Output_to_file=off or
-F.
The Continue_Trace option may not work if the Start_Row option has been set
to anything but the top of the file, depending on the output format being
used.
POV-Ray tries to figure out where to resume an interrupted trace by reading
any previously generated data in the specified output file. All file formats
contain the image size, so this will override any image size settings
specified. Some file formats (namely TGA and PNG) also store information
about where the file started (i.e. +SCn and +SRn options), alpha output (
+UA), and bit-depth ( +FNn), which will override these settings. It is up to
the user to see to it that all other options are set the same as the original
render.
The Create_Ini option or +GI switch provides an easy way to create an INI
file with all of the rendering options, so you can re-run files with the same
options, or ensure you have all the same options when resuming. This option
creates an INI file with every option set at the value used for that
rendering. This includes default values which you have not specified. For
example if you run POV-Ray with...
POVRAY +Isimple.pov MYOPTS +GIrerun.ini MOREOPTS
POV-Ray will create a file called rerun.ini with all of the options used to
generate this scene. The file is not written until all options have been
processed. This means that in the above example, the file will include
options from both MYOPTS.INI and MOREOPTS.INI despite the fact that the +GI
switch is specified between them. You may now re-run the scene with...
POVRAY RERUN
or resume an interrupted trace with
POVRAY RERUN +C
If you add other switches with the RERUN.INI reference, they will be included
in future re-runs because the file is re-written every time you use it.
The Create_Ini option is also useful for documenting how a scene was
rendered. If you render WAYCOOL.POV with Create_Ini=true then it will create
a file WAYCOOL.INI that you could distribute this file along with your scene
file so other users can exactly re-create your image.
2.2.2.2 Display Output Options
2.2.2.2.1 Display Hardware Settings
Display=bool Turns graphic display on/off
+D Turns graphic display on
-D Turns graphic display off
Video_Mode=x Set video mode to 'x'; does not affect on/off
+Dx Set display on; Set mode to 'x'
-Dx Set display off; but for future use mode 'x'
Palette=y Set display palette to 'y'; does not affect on/off
+Dxy Set display on; Set mode 'x'; Set palette 'y'
-Dxy Set display off; use mode 'x', palette 'y' in future
Display_Gamma=n.n Sets the display gamma to n.n
The Display=on or +D switch will turn on the graphics display of the image
while it is being rendered. Even on some non-graphics systems, POV-Ray may
display an 80 by 24 character "ASCII-Art" version of your image. Where
available, the display may be full, 24-bit true color. Setting Display=off or
-D switch will turn off the graphics display which is the default.
The Video_Mode=x option sets the display mode or hardware type chosen where x
is a single digit or letter that is machine dependent. Generally Video_Mode=0
means the default setting or an auto-detected setting should be used. When
using switches, this character immediately follows the switch. For example
the +D0 switch will turn on the graphics display in the default mode.
The Palette=y option selects the palette to be used. Typically the single
character parameter y is a digit which selects one of several fixed palettes
or a letter such G for gray scale, H for 15- bit high color or T for 24-bit
true color. When using switches, this character is the 2nd character after
the switch. For example the +D0T switch will turn on the graphics display in
the default mode with a true color palette.
The Display_Gamma=n.n setting is new with POV-Ray 3.0, and is not available
as a command-line switch. The Display_Gamma setting overcomes the problem of
images (whether ray-traced or not) having different brightness when being
displayed on different monitors, different video cards, and under different
operating systems. Note that the Display_Gamma is a setting based on your
computer's display hardware, and should be set correctly once and not
changed. The Display_Gamma INI setting works in conjunction with the new
assumed_gamma global setting to ensure that POV scenes and the images they
create look the same on all systems. See section "Assumed_Gamma" which
describes the assumed_gamma global setting, and describes gamma more
thoroughly.
While the Display_Gamma can be different for each system, there are a few
general rules that can be used for setting Display_Gamma if you don't know it
exactly. If the Display_Gamma keyword does not appear in the INI file,
POV-Ray assumes that the display gamma is 2.2. This is because most PC
monitors have a gamma value in the range 1.6 to 2.6 (newer models seem to
have a lower gamma value). MacOS has the ability to do gamma correction
inside the system software (based on a user setting in the gamma control
panel). If the gamma control panel is turned off, or is not available, the
default Macintosh system gamma is 1.8. Some high-end PC graphics cards, can
do hardware gamma correction, and should use the current Display_Gamma
setting, usually 1.0. A gamma test image is also available to help users to
set their Display_Gamma accurately.
For scene files that do not have an assumed_gamma global setting the
Display_Gamma will not have any affect on the preview output of POV-Ray or
for most output file formats. However, the Display_Gamma value is used when
creating PNG format output files, and also when rendering the POV-Ray example
files (because they have an assumed_gamma), so it should still be correctly
set for your system to ensure proper results.
2.2.2.2.2 Display Related Settings
Pause_When_Done=bool Sets pause when done on/off
+P Sets pause when done on
-P Sets pause when done off
Verbose=bool Set verbose messages on/off
+V Set verbose messages on
-V Set verbose messages off
Draw_Vistas=bool Turn draw vistas on/off
+UD Turn draw vistas on
-UD Turn draw vistas off
On some systems, when the image is complete, the graphics display is cleared
and POV-Ray switches back into text mode to print the final statistics and to
exit. Normally when the graphics display is on, you want to look at the image
awhile before continuing. The Pause_When_Done=on or +P switch causes POV-Ray
to pause in graphics mode until you to press a key to continue. The default
is off or -P.
When the graphics display is not used, it is often desirable to monitor
progress of the rendering. The Verbose=on or +V switch turns on verbose
reporting of your rendering progress. This reports the number of the line
currently being rendered, the elapsed time for this frame and other
information. On some systems, this textual information can conflict with the
graphics display. You may need to turn this off when the display is on. The
default setting is off or -V.
The option Draw_Vistas=on or +UD was originally a debugging feature for
POV-Ray's vista buffer feature but it was such fun we decided to keep it.
Vista buffering is a spatial sub-division method that projects the 2-D
extents of bounding boxes onto the viewing window. POV-Ray tests the 2-D x,y
pixel location against these rectangular areas to determine quickly which
objects, if any, the viewing ray will hit. This option shows you the 2-D
rectangles used. The default setting is off or - UD because the drawing of
the rectangles can take considerable time on complex scenes and it serves no
critical purpose. See vista buffers for more details.
2.2.2.2.3 Mosaic Preview
Preview_Start_Size=n Set mosaic preview start size to n
+SPn Same as Preview_Start_Size=n
Preview_End_Size=n Set mosaic preview end size to n
+EPn Same as Preview_End_Size=n
Typically while you are developing a scene, you will do many low resolution
test renders to see if objects are placed properly. Often the low res version
doesn't give you sufficient detail and you have to start over at a higher
resolution. A feature called mosaic preview solves this problem by
automatically rendering your image in several passes. The early passes give a
rough overview of the entire image using large blocks of pixels that looks
like mosaic tile. The image is then refined using higher resolution on
subsequent passes. When sufficient resolution has been reached, you can stop
the process or you can let it finish the image at full resolution.
To use this feature you should select a Width and Height value that is the
highest resolution you will need. Mosaic preview is enabled by specifying how
big the mosaic blocks will be on the first pass using Preview_Start_Size=nnn
or +SPnnn. The value nnn should be a number greater than zero that is a power
of two (1,2,4,8,16,32, etc.) If it is not a power of 2, the nearest power of
2 less than nnn is substituted. This sets the size of the squares, measured
in pixels. A value of 16 will draw every 16th pixel as a 16x16 pixel square
on the first pass. Subsequent passes will use half that value such as 8x8,
4x4 and so on.
The process continues until it reaches 1x1 pixels or until it reaches the
size you set with Preview_End_Size=nnn or +EPnnn. Again the value nnn should
be a number greater than zero that is a power of 2. If it is not a power of
2, the nearest power of 2 less than nnn is substituted. The default ending
value is 1.
No file output is performed until the final 1x1 pass is reached. Although the
preliminary passes render only as many pixels as needed, the 1x1 pass
re-renders every pixel so that anti-aliasing and file output streams work
properly. This makes the scene take 25% longer than usual to render so it is
recommended that mosaic preview not be used for final rendering. Also the
lack of file output until the final pass means that renderings which are
interrupted before the 1x1 pass may not be resumed without starting over from
the beginning. Future versions of POV-Ray will include some system of
temporary files or buffers which will eliminate these inefficiencies and
limitations. Mosaic preview is still a useful feature for test renderings.
2.2.2.3 File Output Options
2.2.2.3.1 Output File Type
Output_to_File=bool Sets file output on/off
+F Sets file output on (use default type)
-F Sets file output off
Output_File_Type=x Sets file output format to 'x'
+Fxn Sets file output on; sets format 'x', depth 'n'
-Fxn Sets file output off; but in future use format 'x',
depth 'n'
Output_Alpha=bool Sets alpha output on/off
+UA Sets alpha output on
-UA Sets alpha output off
Output_File_Name=file Sets output file to file
+Ofile Same as Output_File_Name=file
Buffer_Output=bool Turn output buffering on/off
+B Turn output buffering on
-B Turn output buffering off
Buffer_Size=n Set output buffer size to 'n' kilobytes. If n is
zero, no buffering. If n < system default, the system
default is used.
+Bn Turn buffer on, set size n
-Bn Turn buffer off, but for future set size n
Bits_Per_Color=n Sets file output bits/color to 'n'
By default, POV-Ray writes an image file to disk. When you are developing a
scene and doing test renders, the graphic preview may be sufficient. To save
time and disk activity you may turn file output off with Output_to_File=off
or -F.
The default type of image file depends on which platform you are using.
MS-DOS and most others default to 24-bit uncompressed Targa. See your
platform-specific documentation to see what your default file type is. You
may select one of several different file types using Output_File_Type=x or
+Fx where x is one of the following...
+FC Compressed Targa-24 format (RLE, run length encoded)
+FN New PNG (portable network graphics) format
+FP Unix PPM format
+FS System-specific such as Mac Pict or Windows BMP
+FT Uncompressed Targa-24 format
Note that the obsolete +FD dump format and +FR raw format have been dropped
from POV-Ray 3.0 because they were rarely used and no longer necessary. PPM,
PNG, and system specific formats have been added. PPM format images are
uncompressed, and have a simple text header, which makes it a widely portable
image format. PNG is a new image format designed not only to replace GIF, but
to improve on its shortcomings. PNG offers the highest compression available
without loss for high quality applications, such as ray-tracing. The system
specific format depends on the platform used and is covered in the
appropriate system specififc documentation.
Most of these formats output 24 bits per pixel with 8 bits for each of red,
green and blue data. PNG allows you to optionally specify the output bit
depth, from 5 to 16 bits for each of the red, green, and blue colors, giving
from 15 to 48 bits of color information per pixel. The default output depth
for all formats is 8 bits/color (16 million possible colors), but this may be
changed for PNG format files by setting Bits_Per_Color=n or by specifying
+FNn, where n is the desired bit depth.
Specifying a smaller color depth like 5 bits/color (32768 colors) may be
enough for people with 8- or 16-bit (256 or 65536 color) displays, and will
improve compression of the PNG file. Higher bit depths like 10 or 12 may be
useful for video or publishing applications, and 16 bits/color is good for
grayscale height field output (See section "Height Field" for details on
height fields).
Targa format also allows 8 bits of alpha transparency data to be output,
while PNG format allows 5 to 16 bits of alpha transparency data, depending on
the color bit depth as specified above. You may turn this option on with
Output_Alpha=on or +UA. The default is off or -UA. See section "Using the
Alpha Channel" for further details on transparency.
In addition to support for variable bit-depths, alpha channel, and grayscale
formats, PNG files also store the Display_Gamma value so the image displays
properly on all systems (see section "Display Hardware Settings" ). The
HF_Gray_16 global setting, as described in section "HF_Gray_16" will also
affect the type of data written to the output file.
2.2.2.3.2 Output File Name
Output_File_Name=file Sets output file to file
+Ofile Same as Output_File_Name=file
The default output filename is created from the scene name and need not be
specified. The scene name is the input name with all drive, path, and
extension stripped. For example if the input name is
+Ic:\povray3\mystuff\myfile.pov the scene name is myfile. The proper
extension is appended to the scene name based on the file type. For example
myfile.tga or myfile.png might be used.
You may override the default output name with the Output_File_Name=file or
+Ofile option. For example:
Input_File_Name=myinput.pov
Output_File_Name=myoutput.tga
If an output file name of "-" is specified (a single minus sign), then the
output will be written to the standard output, usually the screen. The output
can then be piped into another program or to a GUI if desired.
2.2.2.3.3 Output File Buffer
Buffer_Output=bool Turn output buffering on/off
+B Turn output buffering on
-B Turn output buffering off
Buffer_Size=n Set output buffer size to 'n' kilobytes. If n is zero,
no buffering. If n < system default, the system default
is used.
+Bn Turn buffer on, set size n
-Bn Turn buffer off, but for future set size n
The Buffer_Output and Buffer_Size options and the +B switch allows you to
assign large buffers to the output file. This reduces the amount of time
spent writing to the disk. If this parameter is not specified, then as each
row of pixels is finished, the line is written to the file and the file is
flushed. On most systems, this operation ensures that the file is written to
the disk so that in the event of a system crash or other catastrophic event,
at least part of the picture has been stored properly and retrievable on
disk. The default value is Buffer_Output=off.
2.2.2.4 CPU Utilization Histogram
The CPU utilization histogram is a way of finding out where POV-Ray is
spending its rendering time, as well as an interesting way of generating
heightfields. The histogram splits up the screen into a rectangular grid of
blocks. As POV-Ray renders the image, it calculates the amount of time it
spends rendering each pixel, and then adds this time to the total rendering
time for each grid block. When the rendering is complete, the histogram is a
file which represents how much time was spent computing the pixels in each
grid block.
Note that not all versions of POV-Ray allow the creation of histograms. As
well, the histogram output is dependent on the file type, as well as the
system that POV-Ray is being run on.
2.2.2.4.1 File Type
Histogram_Type=x Set histogram type to x (turn off if type is 'X')
+HTx Same as Histogram_Type=x
The histogram output file type is nearly the same as that used for the image
output file types in "Output File Type" . The available histogram file types
are as follows:
+HTC Comma separated values (CSV) often used in spreadsheets
+HTN New PNG (portable network graphics) format grayscale
+HTP Unix PPM format
+HTS System-specific such as Mac Pict or Windows BMP
+HTT Uncompressed Targa-24 format (TGA)
+HTX No histogram file output is generated
Note that +HTC does not generate a compressed Targa-24 format output file,
but rather a text file with a comma-separated list of the time spent in each
grid block, in left-to-right and top-to bottom order. The units of time
output to the CSV file are system dependent. See the system specific
documentation for further details on the time units in CSV files.
The Targa and PPM format files are in the POV heightfield format (see "Height
Field" ), so the histogram information is stored in both the red and green
parts of the image, which makes it unsuitable for viewing. When used as a
height field, lower values indicate less time spent calculating the pixels in
that block, while higher indicate more time spent in that block.
PNG format images are stored as grayscale images, and are useful for both
viewing the histogram data as well as for use as a heightfield. In PNG files,
the darker (lower) areas indicate less time spent in that grid block, while
the brighter (higher) areas indicate more time spent in that grid block.
2.2.2.4.2 File Name
Histogram_Name=file Set histogram name to file
+HNfile Same as Histogram_Name=file
The histogram file name is the name of the file in which to write the
histogram data. If the file name is not specified, it will default to
"histgram.ext", where ext is based on the file type specified previously.
Note that if the histogram name is specified, the file name extension should
match the file type.
2.2.2.4.3 Grid Size
Histogram_Grid_Size=xx.yy Set histogram grid to xx by yy
+HSxx.yy Same as Histogram_Grid_Size=xx.yy
The histogram grid size gives the number of times the image is split up in
both the horizontal and vertical directions. For example:
povray +Isample +W640 +H480 +HTN +HS160.120 +HNhistogrm.png
will split the image into 160x120 grid blocks, each of size 4x4 pixels, and
output a PNG file, suitable for viewing or for use as a heightfield. Smaller
numbers for the grid size mean more pixels are put into the same grid block.
With CSV output, the number of values output is the same as the number of
grid blocks specified. For the other formats, the image size is identical to
the rendered image, rather than the specified grid size, to allow easy
comparison between the histogram and the rendered image.. If the histogram
grid size is not specified, it will default to the same size as the image, so
there will be one grid block per pixel.
Note that on systems that do task-switching or multi-tasking, the histogram
may not exactly represent the amount of time POV-Ray spent in a given grid
block, since the histogram is based on real time rather than CPU time. As a
result, time may be spent for operating system overhead or on other tasks
running at the same time. This will cause the histogram to have speckling,
noise or large spikes. This can be reduced by decreasing the grid size so
that more pixels are averaged into a given grid block.
2.2.3 Scene Parsing Options
POV-Ray reads in your scene file and processes it to create an internal model
of your scene. The process is called parsing. As it parses your file, it may
read other files along the way. This section covers options concerning what
to parse, where to find it, and what version specific assumptions it should
make while parsing it.
2.2.3.1 Input File Name
Input_File_Name=file Sets input file name to file
+Ifile Same as Input_File_Name=file
You will probably always set this option but if you do not, the default input
filename is object.pov. If you do not have an extension, then .pov is
assumed. On case-sensitive operating systems, both .pov and .POV are tried. A
full path specification may be used. For example:
+Ic:\povray3\mystuff\myfile.pov. In addition to specifying the input file
name, this also establishes the scene name.
The scene name is the input name with all drive, path, and extension
stripped. In this example, the scene name is myfile. This name is used to
create a default output file name and it is referenced other places.
If you use "-" as the input file name the input will be read from standard
input. Using this you can pipe a scene created by a program to POV and render
it without having a scene file.
Under MS-DOS you can try this feature with
type ANYSCENE.POV | povray -i-
2.2.3.2 Library Paths
Library_Path=path Add path to list of library paths
+Lpath Same as Library_Path=path
POV-Ray looks for files in the current directory. If it does not find a file
it needs, it looks in various other library directories which you specify.
POV-Ray does not search your operating system path. It only searches the
current directory and directories which you specify with this option. For
example the standard include files are usually kept in one special directory.
You tell POV-Ray to look there with...
Library_Path=c:\povray3\include
You must not specify any final path seperators (\ or /) at the end.
Multiple uses of this option switch do not override previous settings. Up to
ten unique paths may be specified. If you specify the exact same path twice,
it is only counts once. The current directory will be searched first followed
by the indicated library directories in the order in which you specified
them.
2.2.3.3 Language Version
Version=n.n Set initial language compatibility to version n.n
+MVn.n Same as Version=n.n
While many language changes have been made for POV-Ray 3.0, all of version
2.0 syntax and most of version 1.0 syntax still works. Whenever possible we
try to maintain backwards compatibility. One feature introduced in 2.0 that
was incompatible with any 1.0 scene files is the parsing of float
expressions. Setting +MV1.0 or Version=1.0 turns off expression parsing as
well as many warning messages so that nearly all 1.0 files will still work.
The changes between 2.0 and 3.0 are not as extensive. Setting Version=2.0 is
only necessary to eliminate some warning messages. Naturally the default
setting for this option is Version=3.0
The #version language directive also can be used to change modes several
times within scene files. This option only affects the initial setting.
See "Version Directive" for more details about the language version
directive.
2.2.3.4 Removing User Bounding
Remove_Bounds=bool Turn unnecessary bounds removal on/off
+UR Turn unnecessary bounds removal on
-UR Turn unnecessary bounds removal off
Split_Unions=bool Turn split bounded unions on/off
+SU Turn split bounded unions on
-SU Turn split bounded unions off
Early versions of POV-Ray had no system of automatic bounding or spatial
sub-division to speed up ray-object intersection tests. Users had to manually
create bounding boxes to speed up the rendering. POV-Ray 3.0 has more
sophisticated automatic bounding than any previous version. In many cases the
manual bounding on older scenes is slower than the new automatic systems.
Therefore POV-Ray removes manual bounding when it knows it will help. In rare
instances you may want to keep manual bounding. Some older scenes incorrectly
used bounding when they should have used clipping. In these scenes if POV-Ray
removes the bounds, the image will not look right. To turn off the automatic
removal of manual bounds, you should specify Remove_Bounds=off or -UR. The
default is +UR.
One area where the jury is still out is the splitting of manually bounded
unions. Note unbounded unions are always split into their component parts so
that automatic bounding works better. Most users do not bound unions because
they know that doing so is usually slower. If you do manually bound a union
we presume you really want it bound. For safety sake we do not presume to
remove such bounds. If you want to remove manual bounds from unions, you
should specify Split_Unions=on or +SU. The default is -SU.
2.2.4 Shell-out to Operating System
Pre_Scene_Command=s Set command before entire scene
Pre_Frame_Command=s Set command before each frame
Post_Scene_Command=s Set command after entire scene
Post_Frame_Command=s Set command after each frame
User_Abort_Command=s Set command when user aborts POV-Ray
Fatal_Error_Command=s Set command when POV-Ray has fatal error
Note no +/- switches are available for these options. They cannot be used
from the command line. They may only be used from INI files.
POV-Ray offers you the opportunity to shell-out to the operating system at
several key points to execute another program or batch file. Usually this is
used to manage files created by the internal animation loop however the shell
commands are available for any scene. The CMD is a single line of text which
is passed to the operating system to execute a program. For example:
Post_Scene_Command=tga2gif -d -m myfile
would use the utility tga2gif with the -d and -m parameters to convert
myfile.tga to myfile.gif after the scene had finished rendering.
2.2.4.1 String Substitution in Shell Commands
It could get cumbersome to change the Post_Scene_Command every time you
changed scene names. POV-Ray can substitute various values into a CMD string
for you. For example:
Post_Scene_Command=tga2gif -d -m %s
POV-Ray will substitute the %s with the scene name in the command. The scene
name is the Input_File_Name or +i setting with any drive, directory or
extension removed. For example:
Input_File_Name=c:\povray3\scenes\waycool.pov
is stripped down to the scene name "waycool" which results in...
Post_Scene_Command=tga2gif -d -m waycool
In an animation it may be necessary to have the exact output file name with
the frame number included. The string %o will substitute the output file
name. Suppose you want to save your output files in a zip archive using
pkzip. You could do...
Post_Frame_Command=pkzip -m %s %o
After rendering frame 12 of myscene.pov, POV-Ray would shell to the operating
system with pkzip -m myscene mysce012.tga. The -m switch in pkzip moves
mysce012.tga to myscene.zip and removes it from the directory. Note that %o
includes frame numbers only when in an animation loop. During the
Pre_Scene_Command and Post_Scene_Command, there is no frame number so the
original, unnumbered Output_File_Name is used. Any User_Abort_Command or
Fatal_Error_Command not inside the loop will similarly give an unnumbered %o
substitution.
Here is the complete list of substitutions available for a common string.
%o Output file name with extension and embedded frame number if any
%s Scene name derived by stripping path and ext from input name
%n Frame number of this frame
%k Clock value of this frame
%h Height of image in pixels
%w Width of image in pixels
%% A single % sign.
2.2.4.2 Shell Command Sequencing
Here is the sequence of events in an animation loop. Non-animated scenes work
the exact same way except there is no loop.
1) All INI and switches are processed just once.
2) Open any text output streams and do Create_INI if any
3) Pre_Scene_Command executed if any
4) Loop through frames (or just do once on non-animation)
a) Pre_Frame_Command executed if any
b) Parse entire scene file, open output file and read settings,
turn on display, render the frame, destroy all objects,
textures etc., close output file, close display.
c) Post_Frame_Command executed if any
d) Go back to 4 a until all frames done
5) Post_Scene_Command executed if any
6) Exit POV-Ray.
If the user interrupts processing, the User_Abort_Command, if any, is
executed. User aborts can only occur during the parsing and rendering parts
of step 4b above.
If a fatal error occurs that POV-Ray notices, the Fatal_Error_Command, if
any, is executed. Sometimes an unforeseen bug or memory error could cause a
total crash of the program in which case there is no chance to shell out.
Fatal errors can occur just about anywhere including during the processing of
switches or INI files. If a fatal error occurs before POV-Ray has read the
Fatal_Error_Command string then obviously no shell can occur.
Note that the entire scene is re-parsed for every frame. Future versions of
POV-Ray may allow you to hold over parts of a scene from once frame to the
next but for now, it starts from scratch ever time. Note also that the
Pre_Frame_Command occurs before the scene is parsed. You might use this to
call some custom scene generation utility before each frame. This utility
could rewrite your .POV or .INC files if needed. Perhaps you will want to
generate new .GIF or .TGA files for image maps or height fields on each
frame.
2.2.4.3 Shell Command Return Actions
Pre_Scene_Return=s Set pre scene return actions
Pre_Frame_Return=s Set pre frame return actions
Post_Scene_Return=s Set post scene return actions
Post_Frame_Return=s Set post frame return actions
User_Abort_Return=s Set user abort return actions
Fatal_Error_Return=s Set fatal return actions
Note no +/- switches are available for these options. They cannot be used
from the command line. They may only be used from INI files.
Most operating systems allow application programs to return an error code if
something goes wrong. When POV-Ray executes a shell command, it can make use
of this error code returned from the shell process and take some appropriate
action if the code is zero or non-zero. POV-Ray itself returns such codes. It
returns 0 for success, 1 for fatal error and 2 for user abort.
The actions are designated by a single letter in the different *_Return=s
options. The possible actions are:
I ignore the code
S skip one step
A all steps skipped
Q quit POV-Ray immediately
U generate a user abort in POV-Ray
F generate a fatal error in POV-Ray
For example if your Pre_Frame_Command calls a program which generates your
height field data and that utility fails, then it will return a non-zero
code. We would probably want POV-Ray to abort as well. The option
Pre_Frame_Return=F will cause POV-Ray to do a fatal abort if the
Pre_Frame_Command returns a non-zero code.
Sometimes a non-zero code from the external process is a good thing. Suppose
you want to test if a frame has already been rendered. You could use the S
action to skip this frame if the file is already rendered. Most utilities
report an error if the file is not found. For example the command pkzip -v
myscene mysce012.tga tells pkzip you want to view its catalog for myscene.zip
for the file mysce012.tga. If the file isn't in the archive, pkzip returns a
non-zero code.
However we want to skip if the file is found. Therefore we need to reverse
the ACTION so it skips on zero and doesn't skip on non-zero. To reverse the
zero vs non-zero triggering of an action, precede it with a - sign. (Note a !
will also work. ! is used in many programming languages as a "not" operator).
Pre_Frame_Return=S will skip if the code shows error (non-zero) and will
proceed normally on no error (zero).
Pre_Frame_Return=-S will skip if there is no error (zero) and will proceed
normally if there is an error (non-zero).
The default for all shells is I which means ignore the return action no
matter what. POV-Ray simply proceeds with whatever it was doing before the
shell command. The other actions depend upon the context. You may want to
refer back to the animation loop sequence chart in the previous section. The
action for each shell is as follows...
On return from any User_Abort_Command, if there is an action triggered and
you have specified...
F then turn this user abort into a fatal error. Do the
Fatal_Error_Command, if any. Exit POV-Ray with error code 1.
S, A, Q, or U then proceed with the user abort. Exit POV-Ray with error
code 2.
On return from any Fatal_Error_Command, proceed with the fatal error no
matter what. Exit POV-Ray with error code 1.
On return from any Pre_Scene_Command, Pre_Frame_Command, Post_Frame_Command
or Post_Scene_Commands if there is an action triggered and you have
specified...
F then generate a fatal error. Do the Fatal_Error_Command, if any. Exit
POV-Ray with an error code 1.
U then generate a user abort. Do the User_Abort_Command, if any. Exit
POV-Ray with an error code 2.
Q then quit POV-Ray immediately. Acts as though POV-Ray never really ran.
Do no further shells, (not even Post_Scene_Command) and exit POV-Ray with
an error code 0.
On return from a Pre_Scene_Command, if there is an action triggered and you
haSethen skip rendering all frames. Acts as though the scene completed all
frames normally. Do not do any Pre_Frame_Command or Post_Frame_Commands.
Do the Post_Scene_Command, if any. Exit POV-Ray with error code 0. On the
earlier chart this means skip step #4.
A then skip all scene activity. Works exactly like Q quit. On the earlier
chart this means skip to step #6.
On return from a Pre_Frame_Command, if there is an action triggered and you
have specified...
S then skip only this frame. Acts as though this frame never existed. Do
not do the Post_Frame_Command. Proceed with the next frame. On the
earlier chart this means skip steps #4b and #4c but loop back as needed
in #4d.
A then skip rendering this frame and all remaining frames. Acts as though
the scene completed all frames normally. Do not do any further
Post_Frame_Commands. Do the Post_Scene_Command, if any. Exit POV-Ray with
error code 0. On the earlier chart this means skip the rest of step #4
and proceed at step #5.
On return from a Post_Frame_Command, if there is an action triggered and you
have specified...
S then skip rendering all remaining frames. Acts as though the scene
completed all frames normally. Do the Post_Scene_Command, if any. Exit
POV-Ray with error code 0. On the earlier chart this means skip the rest
of step #4 and proceed at step #5.
A same as S for this shell command.
On return from any Post_Scene_Command, if there is an action triggered and
you have specified...
2.2.5 Text Output
Text output is an important way that POV-Ray keeps you informed about what it
is going to do, what it is doing and what it did. New to POV-Ray 3.0, the
program splits its text messages into 7 separate streams. Some versions of
POV-Ray color codes the various types of text. Some versions allow you to
scroll back several pages of messages. All versions allow you to turn some of
these text streams off/on or to direct a copy of the text output to one or
several files. This section details the options which give you control over
text output.
2.2.5.1 Text Streams
There are seven distinct text streams that POV-Ray uses for output. On some
versions each stream is designated by a particular color. Text from these
streams are displayed whenever it is appropriate so there is often an
intermixing of the text. The distinction is only important if you choose to
turn some of the streams off or to direct some of the streams to text files.
On some systems you may be able to review the streams separately in their own
scroll-back buffer.
Here is a description of each stream.
BANNER: This stream displays the program's sign-on banner, copyright,
contributor's list, and some help screens. It cannot be turned off or
directed to a file because most of this text is displayed before any options
or switches are read. Therefore you cannot use an option or switch to control
it. There are switches which display the help screens. They are covered in
section "Help Screen Switches" .
DEBUG: This stream displays debugging messages. It was primarily designed for
developers but this and other streams may also be used by the user to display
messages from within their scene files. See "Text Message Streams" for
details on this feature. This stream may be turned off and/or directed to a
text file.
FATAL: This stream displays fatal error messages. After displaying this text,
POV-Ray will terminate. When the error is a scene parsing error, you may be
shown several lines of scene text that leads up to the error. This stream may
be turned off and/or directed to a text file.
RENDER: This stream displays information about what options you have
specified to render the scene. It includes feedback on all of the major
options such as scene name, resolution, animation settings, anti-aliasing and
others. This stream may be turned off and/or directed to a text file.
STATISTICS: This stream displays statistics after a frame is rendered. It
includes information about the number of rays traced, the length of time of
the processing and other information. This stream may be turned off and/or
directed to a text file.
STATUS: This stream displays one-line status messages that explain what
POV-Ray is doing at the moment. On some systems this stream is displayed on a
status line at the bottom of the screen. This stream cannot be directed to a
file because there is generally no need to. The text displayed by the Verbose
option or +V switch is output to this stream so that part of the status
stream may be turned off.
WARNING: This stream displays warning messages during the parsing of scene
files and other warnings. Despite the warning, POV-Ray can continue to render
the scene. You will be informed if POV-Ray has made any assumptions about
your scene so that it can proceed. In general any time you see a warning, you
should also assume that this means that future versions of POV-Ray will not
allow the warned action. Therefore you should attempt to eliminate warning
messages so your scene will be able to run in future versions of POV-Ray.
This stream may be turned off and/or directed to a text file.
2.2.5.2 Console Text Output
Debug_Console=bool Turn console display of debug info text on/off
+GD Same as Debug_Console=On
-GD Same as Debug_Console=Off
Fatal_Console=bool Turn console display of fatal error text on/off
+GF Same as Fatal_Console=On
-GF Same as Fatal_Console=Off
Render_Console=bool Turn console display of render info text on/off
+GR Same as Render_Console=On
-GR Same as Render_Console=Off
Statistic_Console=bool Turn console display of statistic text on/off
+GS Same as Statistic_Console=On
-GS Same as Statistic_Console=Off
Warning_Console=bool Turn console display of warning text on/off
+GW Same as Warning_Console=On
-GW Same as Warning_Console=Off
All_Console=bool Turn on/off all debug, fatal, render, statistic and
warning text to console.
+GA Same as All_Console=On
-GA Same as All_Console=Off
You may suppress the output to the console of the Debug, Fatal, Render,
Statistic or Warning text streams. For example the Statistic_Console=off
option or the -GS switch can turn off the Statistic stream. Using on or +GS
you may turn it on again. You may also turn all 5 of these streams on or off
at once using the All_Console option or +GA switch.
Note these options take effect immediately when specified. Obviously any
Error or Warning messages that might occur before the option is read, it will
not be affected.
2.2.5.3 Directing Text Streams to Files
Debug_File=true Echo debug info text to DEBUG.OUT
Debug_File=false Turn off file output of debug info
Debug_File=file Echo debug info text to file
+GDfile Both Debug_Console=On, Debug_File=file
-GDfile Both Debug_Console=Off, Debug_File=file
Fatal_File=true Echo fatal text to FATAL.OUT
Fatal_File=false Turn off file output of fatal
Fatal_File=file Echo fatal info text to file
+GFfile Both Fatal_Console=On, Fatal_File=file
-GFfile Both Fatal_Console=Off, Fatal_File=file
Render_File=true Echo render info text to RENDER.OUT
Render_File=false Turn off file output of render info
Render_File=file Echo render info text to file
+GRfile Both Render_Console=On, Render_File=file
-GRfile Both Render_Console=Off, Render_File=file
Statistic_File=true Echo statistic text to STATS.OUT
Statistic_File=false Turn off file output of statistics
Statistic_File=file Echo statistic text to file
+GSFile Both Statistic_Console=On, Statistic_File=file
-GSFile Both Statistic_Console=Off, Statistic_File=file
Warning_File=true Echo warning info text to WARNING.OUT
Warning_File=false Turn off file output of warning info
Warning_File=file Echo warning info text to file
+GWfile Both Warning_Console=On, Warning_File=file
-GWfile Both Warning_Console=Off, Warning_File=file
All_File=true Echo all debug, fatal, render, statistic and warning
text to ALLTEXT.OUT
All_File=false Turn off file output of all debug, fatal, render,
statistic and warning text
All_File=file Echo all debug, fatal, render, statistic and warning
text to file
+GAfile Both All_Console=On, All_File=file
-GAfile Both All_Console=Off, All_File=file
You may direct a copy of the text streams to a text file for the Debug,
Fatal, Render, Statistic or Warning text streams. For example the
Statistic_File=ssssss option or the +GSsssssss switch. If the string ssssss
is true or any of the other valid true strings then that stream is redirected
to a file with a default name. Valid "true" values are true, yes, on or 1. If
the value is false, the direction to a text file is turned off. Valid "false"
values are false, no, off or 0. Any other string specified turns on file
output and the string is interpreted as the output file name.
Similarly you may specify such a true, false or file name string after a
switch such as +GSfile. You may also direct all 5 of these streams to the
same file using the All_File option or +GA switch. You may not specify the
same file for two or more streams because POV-Ray will fail when it tries to
open or close the same file twice.
Note these options take effect immediately when specified. Obviously any
Error or Warning messages that might occur before the option is read, it will
not be affected.
2.2.5.4 Help Screen Switches
+H or +? Show help screen 0 if this is the only switch
+H0 to +H8 Show help screen 0 to 8 if this is the only switch
+?0 to +?8 Same as +H0 to +H8
Note there are no INI style equivalents to these options.
Graphical interface versions of POV-Ray such as Mac or Windows have extensive
online help. Other versions of POV-Ray have only a few quick-reference help
screens. The +? switch, optionally followed by a single digit from 0 to 8,
will display these help screens to the Banner text stream. After displaying
the help screens, POV-Ray terminates. Because some operating systems do not
permit a question mark as a command line switch, you may also use the +H
switch. Note however that this switch is also used to specify the height of
the image in pixels. Therefore the +H switch is only interpreted as a help
switch if it is the only switch on the command line and if the value after
the switch is less than or equal to 8.
2.2.6 Tracing Options
There is more than one way to trace a ray. Sometimes there is a trade-off
between quality and speed. Sometimes options designed to make tracing faster
can slow things down. This section covers options that tell POV-Ray how to
trace rays with the appropriate speed and quality settings.
2.2.6.1 Quality Settings
Quality=n Set quality value to n (0 <= n <= 10)
+Qn Same as Quality=n
The Quality=nn option or +Qnn switch allows you to specify the image
rendering quality. You may choose to lower the quality for test rendering and
raise it for final renders. The quality adjustments are made by eliminating
some of the calculations that are normally performed. For example settings
below 4 do not render shadows. Settings below 8 do not use reflection or
refraction. The values correspond to the following quality levels:
0,1 Just show quick colors. Use full ambient lighting only. Quick colors
are used only at 5 or below.
2,3 Show specified diffuse and ambient light.
4 Render shadows, but no extended lights. 5 Render shadows, including
extended lights.
6,7 Compute texture patterns.
8 Compute reflected, refracted, and transmitted rays.
9 Compute halos.
10 Use radiosity, but do not calculate halos.
11 Use radiosity and halos.
The default is 9 if not specified. A value of 10 or 11 turns on radiosity.
Radiosity is an additional calculation which computes diffuse
inter-reflection. It is an extremely slow calculation that is somewhat
experimental. The parameters which control how radiosity calculations are
performed are specified in the global_settings {radiosity {...} } statement.
See "Miscellaneous Features" for further details.
2.2.6.2 Automatic Bounding Control
Bounding=bool Turn bounding on/off
+MB Turn bounding on; threshold 25 or prev. amt
-MB Turn bounding off
Bounding_Threshold=n Set bound threshold to n
+MBn Turn bounding on; bound threshold to n
-MBn Turn bounding off; for future threshold to n
Light_Buffer=bool Turn light buffer on/off
+UL Turn light buffer on
-UL Turn light buffer off
Vista_Buffer=bool Turn vista buffer on/off
+UV Turn vista buffer on
-UV Turn vista buffer off
POV-Ray uses a variety of spatial sub-division systems to speed up ray-object
intersection tests. The primary system uses a hierarchy of nested bounding
boxes. This system compartmentalizes all finite objects in a scene into
invisible rectangular boxes that are arranged in a tree-like hierarchy.
Before testing the objects within the bounding boxes the tree is descended
and only those objects are tested whose bounds are hit by a ray. This can
greatly improve rendering speed. However for scenes with only a few objects
the overhead of using a bounding system is not worth the effort. The
Bounding=off option or -MB switch allows you to force bounding off. The
default value is on.
The Bounding_Threshold=nnn or +MBnnn switch allows you to set the minimum
number of objects necessary before bounding is used. The default is +MB25
which means that if your scene has fewer than 25 objects, POV-Ray will
automatically turn bounding off because the overhead isn't worth it.
Additionally POV-Ray uses systems known as vista buffers and light buffers to
further speed things up. These systems only work when bounding is on and when
there are a sufficient number of objects to meet the bounding threshold. The
vista buffer is created by projecting the bounding box hierarchy onto the
screen and determining the rectangular areas that are covered by each of the
elements in the hierarchy. Only those objects whose rectangles enclose a
given pixel are tested by the primary viewing ray. The vista buffer can only
be used with perspective and orthographic cameras because they rely on a
fixed viewpoint and a "reasonable" projection (i.e. lines have to stay lines
after the projection).
The light buffer is created by enclosing each light source in an imaginary
box and projecting the bounding box hierarchy onto each of its six sides.
Since this relies on a fixed light source, light buffers will not be used for
area lights.
Reflected and transmitted rays do not take advantage of the light and vista
buffer.
The default settings are Vista_Buffer=on or +UV and Light_Buffer=on or +UL.
The option to turn these features off is available to demonstrate their
usefulness and as protection against unforeseen bugs which might exist in any
of these bounding systems.
In general, any finite object and many types of CSG of finite objects will
properly respond to this bounding system. In addition blobs and meshes use an
additional internal bounding system. These systems are not affected by the
above switch. They can be switched off using the appropriate syntax in the
scene file (see "Blob" and "Mesh" for details). Text objects are split into
individual letters that are bound using the bounding box hierarchy. Some CSG
combinations of finite and infinite objects are also automatically bound. The
end result is that you will rarely need to add manual bounding objects as was
necessary in earlier versions of POV-Ray unless you use many infinite
objects.
2.2.6.3 Anti-Aliasing Options
Antialias=bool Turns anti-aliasing on/off
+A Turns aa on with threshold 0.3 or previous amount
-A Turns anti-aliasing off
Sampling_Method=n Sets aa-sampling method (1 or 2)
+AMn Same as Sampling_Method=n
Antialias_Threshold=n.n Sets anti-aliasing threshold
+An.n Sets aa on with aa-threshold at n.n
-An.n Sets aa off (aa-threshold n.n in future)
Jitter=bool Sets aa-jitter on/off
+J Sets aa-jitter on with 1.0 or previous amount
-J Sets aa-jitter off
Jitter_Amount=n.n Sets aa-jitter amount to n.n. If n.n <= 0 aa-jitter
is set off
+Jn.n Sets aa-jitter on; jitter amount to n.n. If n.n <=
0 aa-jitter is set off
-Jn.n Sets aa-jitter off (jitter amount n.n in future)
Antialias_Depth=n Sets aa-depth (1 <= n <= 9)
+Rn Same as Antialias_Depth=n
The ray tracing process is in effect a discrete, digital sampling of the
image with typically one sample per pixel. Such sampling can introduce a
variety of errors. This includes a jagged, stair-step appearance in sloping
or curved lines, a broken look for thin lines, moire patterns of interference
and lost detail or missing objects which are so small they reside between
adjacent pixels. The effect that is responsible for those errors is called
aliasing.
Anti-aliasing is any technique used to help eliminate such errors or to
reduce the negative impact they have on the image. In general, anti-aliasing
makes the ray traced image look "smoother". The Antialias=on option or +A
switch turns on POV-Ray's anti-aliasing system.
When anti-aliasing is turned on, POV-Ray attempts to "smooth" the errors by
shooting more than one viewing ray into each pixel and averaging the results
to determine the pixel's apparent color. This technique is called
super-sampling and can improve the appearance of the final image but it
drastically increases the time required to render a scene since many more
calculations have to be done.
POV-Ray gives you the option to use one of two alternate super-sampling
methods. The Sampling_Method=n option or +AMn switch selects non-adaptive
super-sampling (method 1) or adaptive super-sampling (method 2).
In the default, non-adaptive method (+am1), POV-Ray initially traces one ray
per pixel. If the color of a pixel differs from its neighbor (to the left or
above) by more than a threshold value, then the pixel is super-sampled by
shooting a given, fixed number of additional rays. The default threshold is
0.3 but it may be changed using the Antialias_Threshold=n.n option. When the
switches are used, the threshold may optionally follow the +A. For example
+A0.1 turns anti-aliasing on and sets the threshold to 0.1.
The threshold comparison is computed as follows. If r1, g1, b1 and r2, g2, b2
are the rgb components of two pixels then the difference between pixels is
computed by:
diff = abs(r1-r2) + abs(g1-g2) + abs(b1-b2)
If this difference is greater than the threshold both pixels are
super-sampled. The rgb values are in the range 0.0 to 1.0 thus the most two
pixels can differ is 3.0. If the anti-aliasing threshold is 0.0, then every
pixel is super-sampled. If the threshold is 3.0, then no anti-aliasing is
done. Lower threshold means more anti-aliasing and also more time. Use
anti-aliasing for your final version of a picture, not the rough draft. The
lower the contrast, the lower the threshold should be. Higher contrast
pictures can get away with higher tolerance values. Good values seem to be
around 0.2 to 0.4.
When using the non-adaptive method, the default number of super-samples is 9
per pixel, located on a 3x3 grid). The Antialias_Depth=n option or +Rn switch
controls the number of rows and columns of samples taken for a super-sampled
pixel. For example +R4 would give 4x4=16 samples per pixel.
The second, adaptive super-sampling method starts by tracing four rays at the
corners of each pixel. If the resulting colors differ more than the threshold
amount additional samples are taken. This is done recursively, i.e. the pixel
is divided into four sub-pixels that are separately traced and tested for
further subdivision. The advantage of this method is the reduced number of
rays that have to be traced. Samples that are common among adjacent pixels
and sub-pixels are stored and reused to avoid re-tracing of rays. The
recursive character of this method makes it adaptive, i.e. the super-sampling
concentrates on those parts of the pixel that are more likely to need
super-sampling.
The maximum number of subdivisions is specified by the Antialias_Depth=n
option or +Rn switch. This is different from the non-adaptive method were the
total number of super-samples is specified. A maximum number of n
subdivisions results in a maximum number of samples per pixel that is given
by the following table.
Number of samples per Maximum number of samples
super-sampled pixel for per super-sampled pixel for
+Rn the non-adaptive method the adaptive method
1 1 9
2 4 25
3 9 81
4 16 289
5 25 1089
6 36 4225
7 49 16641
8 64 66049
9 81 263169
You should note that the maximum number of samples is hardly ever reached for
a given pixel because of the adaptive sampling. If the adaptive method is
used with no anti-aliasing each pixel will be the average of the rays traced
at its corners. In most cases it does not make sense to use a recursion level
greater than 3.
Another way to reduce aliasing artifacts is to introduce noise into the
sampling process. This is called "jittering" and works because the human
visual system is much more forgiving to noise than it is to regular patterns.
The location of the super-samples is jittered or wiggled a tiny amount when
anti-aliasing is used. Jittering is used by default but it may be turned off
with the Jitter=off option or -J switch. The amount of jittering can be set
with the Jitter_Scale=n.nn option. When using switches the jitter scale may
be specified after the +J switch. For example +J0.5 uses half the normal
jitter. The default amount of 1.0 is the maximum jitter which will insure
that all super-samples remain inside the original pixel. Note that the
jittering "noise" is random and non-repeatable so you should avoid using
jitter in animation sequences, as the anti-aliased pixels will vary and
flicker annoyingly from frame to frame.
If
anti-aliasing is not used one sample per pixel is taken regardless of the
super-sampling method specified.
3 Scene Description Language
The Scene Description Language allows you to describe the world in a readable
and convenient way. Files are created in plain ASCII text using an editor of
your choice. The input file name is specified using the Input_File=file
option or +Ifile switch. By default the files have the extension .POV.
POV-Ray reads the file, processes it by creating an internal model of the
scene and then renders the scene.
The overall syntax of a scene is a file that contains any number of the
following items in any order.
LANGUAGE_DIRECTIVES
camera{ CAMERA_ITEMS }
OBJECT_STATEMENTS
ATMOSPHERE_STATEMENTS
global_settings { GLOBAL_ITEMS }
See "Language Directives" , "Objects" , "Camera" , "Atmospheric Effects" ,
and "Global Settings" for details.
3.1 Language Basics
The POV-Ray language consists of identifiers, reserved keywords, floating
point expressions, strings, special symbols and comments. The text of a
POV-Ray scene file is free format. You may put statements on separate lines
or on the same line as you desire. You may add blank lines, spaces or
indentations as long as you do not split any keywords or identifiers.
3.1.1 Identifiers and Keywords
POV-Ray allows you to define identifiers for later use in the scene file. An
identifier may be 1 to 40 characters long. It may consist of upper or lower
case letters, the digits 0 through 9 or an underscore character. The first
character must be an alphabetic character. The declaration of identifiers is
covered later.
POV-Ray has a number of reserved keywords which are listed below.
aa_level fog_alt range
aa_threshold fog_offset reciprocal
abs fog_type recursion_limit
acos frequency red
acosh gif reflection
adaptive global_settings refraction
adc_bailout glowing render
agate gradient repeat
agate_turb granite rgb
all gray_threshold rgbf
alpha green rgbft
ambient halo rgbt
ambient_light height_field right
angle hexagon ripples
aperture hf_gray_16 rotate
arc_angle hierarchy roughness
area_light hollow samples
asc hypercomplex scale
asin if scallop_wave
asinh ifdef scattering
assumed_gamma iff shadowless
atan image_map sin
atan2 incidence sine_wave
atanh include sinh
atmosphere int sky
atmospheric_attenuation interpolate sky_sphere
attenuating intersection slice
average inverse slope_map
background ior smooth
bicubic_patch irid smooth_triangle
black_hole irid_wavelength sor
blob jitter specular
blue julia_fractal sphere
blur_samples lambda spherical_mapping
bounded_by lathe spiral
box leopard spiral1
box_mapping light_source spiral2
bozo linear spotlight
break linear_spline spotted
brick linear_sweep sqr
brick_size location sqrt
brightness log statistics
brilliance looks_like str
bumps look_at strcmp
bumpy1 low_error_factor strength
bumpy2 mandel strlen
bumpy3 map_type strlwr
bump_map marble strupr
bump_size material_map sturm
camera matrix substr
case max superellipsoid
caustics max_intersections switch
ceil max_iteration sys
checker max_trace_level t
chr max_value tan
clipped_by merge tanh
clock mesh test_camera_1
color metallic test_camera_2
color_map min test_camera_3
colour minimum_reuse test_camera_4
colour_map mod text
component mortar texture
composite nearest_count texture_map
concat no tga
cone normal thickness
confidence normal_map threshold
conic_sweep no_shadow tightness
constant number_of_waves tile2
control0 object tiles
control1 octaves torus
cos off track
cosh offset transform
count omega translate
crackle omnimax transmit
crand on triangle
cube once triangle_wave
cubic onion true
cubic_spline open ttf
cylinder orthographic turbulence
cylindrical_mapping panoramic turb_depth
debug pattern1 type
declare pattern2 u
default pattern3 ultra_wide_angle
degrees perspective union
dents pgm up
difference phase use_color
diffuse phong use_colour
direction phong_size use_index
disc pi u_steps
distance pigment v
distance_maximum pigment_map val
div planar_mapping variance
dust plane vaxis_rotate
dust_type png vcross
eccentricity point_at vdot
else poly version
emitting polygon vlength
end pot vnormalize
error pow volume_object
error_bound ppm volume_rendered
exp precision vol_with_light
exponent prism vrotate
fade_distance pwr v_steps
fade_power quadratic_spline warning
falloff quadric warp
falloff_angle quartic water_level
false quaternion waves
file_exists quick_color while
filter quick_colour width
finish quilted wood
fisheye radial wrinkles
flatness radians x
flip radiosity y
floor radius yes
focal_point rainbow z
fog ramp_wave
All reserved words are fully lower case. Therefore it is recommended that
your identifiers contain at least one upper case character so it is sure to
avoid conflict with reserved words.
The following keywords are in the above list of reserved keywords but are not
currently used by POV-Ray however they remain reserved.
bumpy1 test_camera_1
bumpy2 test_camera_2
bumpy3 test_camera_3
incidence test_camera_4
pattern1 track
pattern2 volume_object
pattern3 volume_rendered
spiral vol_with_light
3.1.2 Comments
Comments are text in the scene file included to make the scene file easier to
read or understand. They are ignored by the ray tracer and are there for your
information. There are two types of comments in POV-Ray.
Two slashes are used for single line comments. Anything on a line after a
double slash // is ignored by the ray tracer. For example:
// This line is ignored
You can have scene file information on the line in front of the comment, as
in:
object { FooBar } // this is an object
The other type of comment is used for multiple lines. This It starts with /*
and ends with */. Everything in-between is ignored. For example:
/* These lines
Are ignored
By the
Ray-tracer */
This can be useful if you want to temporarily remove elements from a scene
file. /*...*/ comments can "comment out" lines containing other // comments,
and thus can be used to temporarily or permanently comment out parts of a
scene. /*..*/ comments can be nested, the following is legal:
/* This is a comment
// This too
/* This also */
*/
Use comments liberally and generously. Well used, they really improve the
readability of scene files.
3.1.3 Float Expressions
Many parts of the POV-Ray language require you to specify one or more
floating point numbers. A floating point number is a number with a decimal
point. Floats may be specified using literals, identifiers or functions which
return float values. You may also create very complex float expressions from
combinations of any of these using various familiar operators.
Where POV-Ray needs an integer value it allows you to specify a float value
and it truncates it to an integer. When POV-Ray needs a logical or boolean
value it interprets any non-zero float as true and zero as false. Because
float comparisons are subject to rounding errors, POV-Ray accepts values
extremely close to zero as being false when doing boolean functions.
Typically values whose absolute values are less than a preset value EPSILON
are considered false for logical expressions. The value of EPSILON is system
dependent but is generally about 1.0e-10. When comparing two floats A and B
for equality, if abs(A-B)<EPSILON then (A=B) is considered true.
3.1.3.1 Float Literals
Float literals are represented by an optional sign (-), some digits, an
optional decimal point, and more digits. If the number is an integer you may
omit the decimal point and trailing zero. If it is all fractional you may
omit the leading zero. POV-Ray supports scientific notation for very large or
very small numbers. The following are all valid float literals:
-2.0 -4 34 3.4e6 2e-5 .3 0.6
3.1.3.2 Float Identifiers
Float identifiers may be declared to make scene files more readable and to
parameterize scenes so that changing a single declaration changes many
values. An identifier is declared as follows...
#declare IDENTIFIER = EXPRESSION
Where IDENTIFIER is the name of the identifier up to 40 characters long and
EXPRESSION is any valid expression which evaluates to a float value. Here are
some examples...
#declare Count = 0
#declare Rows = 5
#declare Cols = 6
#declare Number = Rows*Cols
#declare Count = Count+1
As the last example shows, you can re-declare a float identifier and may use
previously declared values in that re-declaration. There are several built-in
identifiers which POV-Ray declares for you. See "Built-in Identifiers" for
details.
3.1.3.3 Float Operators
Arithmetic float expressions can be created from float literals, identifiers
or functions using the following operators in this order of precedence...
() expressions in parentheses first
+A -A !A unary minus, unary plus and logical "not"
A*B A/B multiplication and division
A+B A-B addition and subtraction
Relational, logical, and conditional expressions may also be created. However
there is a restriction that these types of expressions must be enclosed in
parentheses first. This restriction, which is not imposed by most computer
languages, is necessary because POV-Ray allows mixing of float and vector
expressions. Without the parentheses there is an ambiguity problem.
Parentheses are not required for the unary logical not operator "!" as shown
above. The operators and their precedence are shown here.
Relational: Operands are arithmetic expressions. Result is always boolean
with 1 for true, 0 for false. All relational operators have the same
precedence.
(A < B) A is less than B
(A <= B) A is less than or equal to B
(A = B) A is equal to B (actually abs(A-B)<EPSILON)
(A != B) A is not equal to B (actually abs(A-B)>=EPSILON)
(A >= B) A is greater than or equal to B
(A > B) A is greater than B
Logical: Operands are converted to boolean values of 0 for false and 1 for
true. Result is always boolean. All logical operators have the same
precedence. Note these are not bitwise, they are logical.
(A & B) true only if both A and B are true, false otherwise
(A | B) true if either A or B or both are true
Conditional: Operand C is boolean. A and B are any expressions. Result is
always whatever A or B are.
(C ? A : B) if C then A else B
Assuming the various identifiers have been declared, the following are
examples of valid expressions...
1+2+3 2*5 1/3 Row*3 Col*5
(Offset-5)/2 This/That+Other*Thing
((This<That) & (Other>=Thing)?Foo:Bar)
Expressions are evaluated left to right with innermost parentheses evaluated
first, then unary +, - or !, then multiply or divide, then add or subtract,
then relational, then logical, then conditional.
3.1.4 Vector Expressions
POV-Ray often requires you to specify a vector. A vector is a set of related
float values. Vectors may be specified using literals, identifiers or
functions which return vector values. You may also create very complex vector
expressions from combinations of any of these using various familiar
operators.
POV-Ray vectors may have from two to five components but the vast majority of
vectors have three components. Unless specified otherwise, you should assume
that the word "vector" means a three component vector. POV-Ray operates in a
3D x,y,z coordinate system and you will use three component vectors to
specify x, y and z values. In some places POV-Ray needs only two coordinates.
These are often specified by a 2D vector called a UV vector. Fractal objects
use a 4D vector. Color expressions use 5D vectors but allow you to specify 3,
4 or 5 components and use default values for the unspecified components.
Unless otherwise noted, all 2, 4 or 5 component vectors work just like 3D
vectors but they have a different number of components.
3.1.4.1 Vector Literals
Vectors consist of from two to five float expressions that are bracketed by
angle brackets < and >. The terms are separated by commas. For example here
is a typical three component vector:
< 1.0, 3.2, -5.4578 >
The commas between components are necessary to keep the program from thinking
that the 2nd term is a single float expression "3.2-5.4578" and that there is
no 3rd term. If you see an error message such as Float expected but '>' found
instead it probably means two floats were combined because a comma was
missing.
Sometimes POV-Ray requires you to specify floats and vectors side-by-side.
The rules for vector expressions allow for mixing of vectors with vectors or
vectors with floats so commas are required separators whenever an ambiguity
might arise. For example <1,2,3> -4 evaluates as a mixed float and vector
expression where 4 is subtracted from each component resulting in <-3,-2,-1>
however the comma here <1,2,3>,-4 means this is a vector followed by a float.
Each component may be a full float expression. For example
<This+3,That/3,5*Other_Thing> is a valid vector.
3.1.4.2 Vector Identifiers
Vector identifiers may be declared to make scene files more readable and to
parameterize scenes so that changing a single declaration changes many
values. An identifier is declared as follows...
#declare IDENTIFIER = EXPRESSION
Where IDENTIFIER is the name of the identifier up to 40 characters long and
EXPRESSION is any valid expression which evaluates to a vector value. Here
are some examples...
#declare Here = <1,2,3>
#declare There = <3,4,5>
#declare Jump = <Foo*2,Bar-1,Bob/3>
#declare Route = There-Here
#declare Jump = Jump+<1,2,3>
Note that you invoke a vector identifier by using its name without any angle
brackets. As the last example shows, you can re-declare a vector identifier
and may use previously declared values in that re-declaration. There are
several built-in identifiers which POV-Ray declares for you. See "Built-in
Identifiers" for details.
3.1.4.3 Vector Operators
Vector literals, identifiers and functions may also be combined in
expressions the same as float values. Operations are performed on a
component-by-component basis. For example <1,2,3>+<4,5,6> evaluates the same
as <1+5,2+5,6+9> or <5,7,9>. Other operations are done on a similar
component-by-component basis. For example (<1,2,3> = <3,2,1>) evaluates to
<0,1,0> because the middle components are equal but the others are not.
Admittedly this isn't very useful but its consistent with other vector
operations.
Conditional expressions such as (C?A:B) require that C is a float expression
but A and B may be vector expressions. The result is that the entire
conditional evaluates as a valid vector. For example if Foo and Bar are
floats then ( Foo < Bar ? <1,2,3> : <5,6,7>) evaluates as the vector <1,2,3>
if Foo is less than Bar and evaluates as <5,6,7> otherwise.
You may use the dot operator to extract a single component from a vector.
Suppose the identifier "Spot" was previously defined as a vector. Then Spot.x
is a float value that is the first component of this x,y,z vector. Similarly
Spot.y and Spot.z reference the 2nd and 3rd components. If Spot was a two
component uv_vector you could use Spot.u and Spot.v to extract the first and
second component. For a 4D vector use .x .y .z and .t to extract each float
component. The dot operator is also used in color expressions which are
covered later.
3.1.4.4 Operator Promotion
You may use a lone float expression to define a vector whose components are
all the same. POV-Ray knows when it needs a vector of a particular type and
will promote a float into a vector if need be. For example the POV-Ray scale
statement requires a three component vector. If you specify scale 5 then
POV-Ray interprets this as scale <5,5,5> which means you want to scale by 5
in every direction.
Versions of POV-Ray prior to 3.0 only allowed such use of a float as a vector
in various limited places such as scale and turbulence. However you may now
use this trick anywhere. For example...
box{0,1} // This is the same as box{<0,0,0>,<1,1,1>}
sphere{0,1} // This is the same as sphere{<0,0,0>,1}
This automatic promotion is especially useful because it lets you mix floats
and vectors in the same expression. For example in 3*<1,2,3> the 3 is
promoted to <3,3,3> thus the expression is <3,3,3>*<1,2,3> which evaluates as
<3,6,9>.
When promoting a float into a vector of 2, 3, 4 or 5 components, all
components are set to the float value, however when promoting a vector of a
lower number of components into a higher order vector, all remaining
components are set to zero. For example if POV-Ray expects a 4D vector and
you specify 9 the result is <9,9,9,9> but if you specify <7,6> the result is
<7,6,0,0>.
3.1.5 Specifying Colors
POV-Ray often requires you to specify a color. Colors consist of five values
or color components. The first three are called red, green and blue. They
specify the intensity of the primary colors, red, green and blue using an
additive color system like the one used by the red, green and blue color
phosphors on a color monitor.
The 4th component, called filter, specifies the amount of filtered
transparency of a substance. Some real-world examples of filtered
transparency are stained glass windows or tinted cellophane. The light
passing through such objects is tinted by the appropriate color as the
material selectively absorbs some frequencies of light while allowing others
to pass through. The color of the object is subtracted from the light passing
through so this is called subtractive transparency.
The 5th component, called transmit, specifies the amount of non-filtered
light that is transmitted through a surface. Some real-world examples of
non-filtered transparency are thin see-through cloth, fine mesh netting and
dust on a surface. In these examples, all frequencies of light are allowed to
pass through tiny holes in the surface. Although the amount of light passing
through is diminished, the color of the light passing through is unchanged.
The color of the object is added to the light passing through so this is
called additive transparency.
Note: Early versions of POV-Ray used the keyword alpha to specify filtered
transparency however that word is often used to descrbe non-filtered
transparency. For this reason, alpha is no longer used.
Each of the five components of a color are float values which are normally in
the range between 0.0 and 1.0 however any values, even negatives may be used.
Colors may be specified using vectors, keywords with floats, or identifiers.
You may also create very complex color expressions from combinations any of
these using various familiar operators. The syntax for specifying a color has
evolved since POV-Ray was first released. We have maintained the original
keyword-based syntax and added a short-cut vector notation. Either the old or
new syntax is acceptable however the vector syntax is easier to use when
creating color expressions.
3.1.5.1 Color Vectors
The syntax for a color vector is any of the following...
color rgb VECTOR3
color rgbf VECTOR4
color rgbt VECTOR4
color rgbft VECTOR5
where VECTOR3, VECTOR4 or VECTOR5 are any valid vector expressions of 3, 4 or
5 components. For example
color rgb <1.0, 0.5, 0.2>
This specifies a color whose red component is 1.0 or 100% of full intensity;
the green component is 0.5 or 50% of full intensity and the blue component is
0.2 or 20% of full intensity. Although the filter and transmit components are
not explicitly specified, they exist and are set to their default values of 0
or no transparency.
The rgbf keyword requires a four component vector. The 4th component is the
filter component and the transmit component defaults to zero. Similarly the
rgbt keyword requires four components where the 4th value is moved to the 5th
component which is transmit and then the filter component is set to zero.
The rgbft keyword allows you to specify all five components. Internally in
expressions all five are always used.
Under most circumstances the keyword color is optional and may be omitted. We
also support the British or Canadian spelling colour. Under some
circumstances, if the vector expression is a 5 component expression or there
is a color identifier in the expression then the rgbtf keyword is optional.
3.1.5.2 Color Keywords
The older keyword method of specifying a color is still useful and many users
prefer it. Like a color vector, you begin with the optional keyword color.
This is followed by any of five additional keywords red, green, blue, filter,
or transmit. Each of these component keywords is followed by a float
expression. For example
color red 1.0 green 0.5
This specifies a color whose red component is 1.0 or 100% of full intensity
and the green component is 0.5 or 50% of full intensity. Although the blue,
filter and transmit components are not explicitly specified, they exist and
are set to their default values of 0. The component keywords may be given in
any order and if any component is unspecified its value defaults to zero.
3.1.5.3 Color Identifiers
Color identifiers may be declared to make scene files more readable and to
parameterize scenes so that changing a single declaration changes many
values. A color identifier is declared as either of the following...
#declare IDENTIFIER = COLOR_VECTOR
#declare IDENTIFIER = COLOR_KEYWORDS...
Where IDENTIFIER is the name of the identifier up to 40 characters long and
COLOR_VECTOR or COLOR_KEYWORDS are any valid color specifications as
described in the two previous sections of this document. Here are some
examples...
#declare White = rgb <1,1,1>
#declare Cyan = color blue 1.0 green 1.0
#declare Weird = rgb <Foo*2,Bar-1,Bob/3>
#declare LightGray = White*0.8
#declare LightCyan = Cyan red 0.6
As the LightGray example shows, you do not need any color keywords when
creating color expressions based on previously declared colors. The last
example shows you may use a color identifier with the keyword style syntax.
WARNING: Make sure the identifier is first before any other component
keywords.
Like floats and vectors, you may re-define colors throughout a scene but the
need to do so is rare.
3.1.5.4 Color Operators
Color vectors may be combined in expressions the same as float or vector
values. Operations are performed on a component-by-component basis. For
example rgb <1.0, 0.5 0.2> * 0.9 evaluates the same as rgb <1.0, 0.5 0.2> *
<0.9, 0.9, 0.9> or rgb <0.9, 0.45, 0.18>. Other operations are done on a
similar component-by-component basis.
You may use the dot operator to extract a single component from a color.
Suppose the identifier "Shade" was previously defined as a color. Then
Shade.red is the float value of the red component of Shade. Similarly
Shade.green Shade.blue Shade.filter and Shade.transmit extract the float
value of the other color components.
3.1.5.5 Common Color Pitfalls
The variety and complexity of color specification methods can lead to some
common mistakes. Here are some things to consider when specifying a color.
When using filter transparency, the colors which come through are multiplied
by the primary color components. For example if grey light such as
rgb<0.9,0.9,0.9> passes through a filter such as rgbf<1.0,0.5,0.0,1.0> the
result is rgb<0.9,0.45,0.0> with the red let through 100%, the green cut in
half from 0.9 to 0.45 and the blue totally blocked. Often users mistakenly
specify a clear object by
color filter 1.0
but this has implied red, green and blue values of zero. You've just
specified a totally black filter so no light passes through. The correct way
is either:
color red 1.0 green 1.0 blue 1.0 filter 1.0
or:
color transmit 1.0
In the 2nd example it doesn't matter what the rgb values are. All of the
light passes through untouched.
Another pitfall is the use of color identifiers and expressions with color
keywords. For example...
color My_Color red 0.5
this substitutes whatever was the red component of My_Color with a red
component of 0.5 however...
color My_Color + red 0.5
adds 0.5 to the red component of My_Color and even less obvious...
color My_Color * red 0.5
this cuts the red component in half as you would expect but it also
multiplies the green, blue, filter and transmit components by zero! The part
of the expression after the multiply operator evaluates to rgbft<0.5,0,0,0,0>
as a full 5 component color.
The following example results in no change to My_Color.
color red 0.5 My_Color
that is because the identifier fully overwrites the previous value. When
using identifiers with color keywords, the identifier should be first.
One final issue, some POV-Ray syntax allows full color specifications but
only uses the rgb part. In these cases it is legal to use a float where a
color is needed. For example:
finish{ambient 1}
The ambient keyword expects a color so the value 1 is promoted to <1,1,1,1,1>
which is no problem. However
pigment{color 0.4}
is legal but it may or may not be what you intended. The 0.4 is promoted to
<0.4,0.4,0.4,0.4,0.4> with the filter and transmit set to 0.4 as well. It is
more likely you wanted...
pigment{color rgb 0.4}
in which case a 3 component vector is expected. Therefore the 0.4 is promoted
to <0.4,0.4,0.4,0.0,0.0> with default zero for filter and transmit.
3.1.6 Strings
The POV-Ray language requires you to specify a string of characters to be
used as a file name, text for messages or text for a text object. Strings may
be specified using literals, identifiers or functions which return string
values. Although you cannot build string expressions from symbolic operators
such as are used with floats, vectors, or colors, you may perform various
string operations using string functions. Some applications of strings in
POV-Ray allow for non-printing formatting characters such as newline or
form-feed.
3.1.6.1 String Literals
String literals begin with a double quote mark " which is followed by up to
256 printable ASCII characters and are terminated by another double quote
mark. The following are all valid string literals:
"Here" "There" "myfile.gif" "textures.inc"
3.1.6.2 String Identifiers
String identifiers may be declared to make scene files more readable and to
parameterize scenes so that changing a single declaration changes many
values. An identifier is declared as follows...
#declare IDENTIFIER = STRING
Where IDENTIFIER is the name of the identifier up to 40 characters long and
STRING is a string literal, string identifier or function which returns a
string value. Here are some examples...
#declare Font_Name = "ariel.ttf"
#declare Inc_File = "myfile.inc"
#declare Name = "John"
#declare Name = concat(Name," Doe")
As the last example shows, you can re-declare a string identifier and may use
previously declared values in that re-declaration.
3.1.7 Built-in Identifiers
There are several built-in float and vector identifiers. You can use them to
specify values or to create expressions but you cannot re-declare them to
change their values.
3.1.7.1 Constant Built-in Identifiers
Most built-in identifiers never change value. They are defined as though the
following lines were at the start of every scene.
#declare pi = 3.1415926535897932384626
#declare true = 1
#declare yes = 1
#declare on = 1
#declare false = 0
#declare no = 0
#declare off = 0
#declare u = <1,0>
#declare v = <0,1>
#declare x = <1,0,0>
#declare y = <0,1,0>
#declare z = <0,0,1>
#declare t = <0,0,0,1>
The built-in float identifier pi is obviously useful in math expressions
involving circles.
The built-in float identifiers on off yes no true false are designed for use
as boolean constants.
The built-in vector identifiers x y and z provide much greater readability
for your scene files when used in vector expressions. For example....
plane {y,1} // The normal vector is obviously "y".
plane {<0,1,0>,1} // This is harder to read.
translate 5*x // Move 5 units in the "x" direction.
translate <5,0,0> // This is less obvious.
An expression like 5*x evaluates to 5*<1,0,0> or <5,0,0>.
Similarly u and v may be used in 2D vectors. When using 4D vectors you should
use x y z and t and POV-Ray will promote x y and z to 4D when used where 4D
is required.
3.1.7.2 Built-in Identifier 'clock'
A built-in float identifier clock is used to control animations in POV-Ray.
Unlike some animation packages, the action in POV-Ray animated scenes do not
depend upon the integer frame numbers. Rather you should design your scenes
based upon the float identifier clock. For non-animated scenes its default
value is 0 but you can set it to any float value using the INI file option
Clock=nn.nnn or the command-line switch +Knn.nnn to pass a single float value
your scene file.
Other INI options and switches may be used to animate scenes by automatically
looping through the rendering of frames using various values for clock. By
default, the clock value is 0 for the initial frame and 1 for the final
frame. All other frames are interpolated between these values. For example if
your object is supposed to rotate one full turn over the course of the
animation, you could specify rotate 360*clock*y Then as clock runs from 0 to
1, the object rotates about the y-axis from 0 to 360 degrees.
Although the value of clock will change from frame-to-frame, it will never
change throughout the parsing of a scene.
3.1.7.3 Built-in Identifier 'version'
The built-in float identifier version contains the current setting of the
version compatibility option. Although this value defaults to 3 which is the
current POV-Ray version number, the initial value of version may be set by
the INI file option Version=n.nn or by the +MVn.nn command-line switch. This
tells POV-Ray to parse the scene file using syntax from an earlier version of
POV-Ray.
The INI option or switch only affects the initial setting. Unlike other
built-in identifiers, you may change the value of version throughout a scene
file. You do not use #declare to change it. The #version language directive
is used to change modes. Such changes may occur several times within scene
files.
Together with the built-in version identifier, the #version directive allows
you to save and restore the previous values of this compatibility setting.
For example suppose MYSTUFF.INC is in version 1 format. At the top of the
file you could put:
#declare Temp_Vers = version // Save previous value
#version 1.0 // Change to 1.0 mode
... // Version 1.0 stuff goes here...
#version Temp_Vers // Restore previous version
3.1.8 Functions
POV-Ray defines a variety of built-in functions for manipulating floats,
vectors and strings. The functions are listed grouped according to their
usage and not by the type of value they return. For example vdot computes the
dot product of two vectors and is listed as a vector function even though it
returns a single float value.
Function calls consist of a keyword which specifies the name of the function
followed by a parameter list enclosed in parentheses. Parameters are
separated by commas. For example:
keyword(param1,param2)
Functions evaluate to values that are floats, vectors or strings and may be
used in expressions or statements anywhere that literals or identifiers of
that type may be used.
3.1.8.1 Float Functions
The following are the functions which take one or more float parameters and
return float values. Assume that A and B are any valid expression that
evaluates to a float. See "Vector Functions" and "String Functions" for other
functions which return float values but whose primary purpose is more closely
related to vectors and strings.
abs(A): Absolute value of A. If A is negative, returns -A otherwise returns
A.
acos(A): Arc-cosine of A. Returns the angle, measured in radians, whose
cosine is A.
asin(A): Arc-sine of A. Returns the angle, measured in radians, whose sine is
A.
atan2(A,B): Arc-tangent of (A/B). Returns the angle, measured in radians,
whose tangent is (A/B). Returns appropriate value even if B is zero. Use
atan2(A,1) to compute usual atan(A) function.
ceil(A): Ceiling of A. Returns the smallest integer greater than A. Rounds up
to the next higher integer.
cos(A): Cosine of A. Returns the cosine of the angle A, where A is measured
in radians.
degrees(A): Convert radians to degrees. Returns the angle measured in degrees
whose value in radians is A. Formula is degrees=A/pi*180.0.
div(A,B): Integer division. The integer part of (A/B).
exp(A): Exponential of A. Returns the value of e raised to the A power where
e is the non-repeating value approximately equal to 2.71828182846 the base of
natural logarithms.
floor(A): Floor of A. Returns the largest integer less than A. Rounds down to
the next lower integer.
int(A): Integer part of A. Returns the truncated integer part of A. Rounds
towards zero.
log(A): Natural logarithm of A. Returns the natural logarithm base e of the
value A where e is the non-repeating value approximately equal to
2.71828182846.
max(A,B): Maximum of A and B. Returns A if A larger than B. Otherwise returns
B.
min(A,B): Minimum of A and B. Returns A if A smaller than B. Otherwise
returns B.
mod(A,B): Value of A modulo A. Returns the remainder after the integer
division of A/B. Formula is mod=((A/B)-int(A/B))*B.
pow(A,B): Exponentiation. Returns the value of A raised to the power B.
radians(A): Convert degrees to radians. Returns the angle measured in radians
whose value in degrees is A. Formula is radians=A*pi/180.0.
sin(A): Sine of A. Returns the sine of the angle A, where A is measured in
radians.
sqrt(A): Square root of A. Returns the value whose square is A.
tan(A): Tangent of A. Returns the tangent of the angle A, where A is measured
in radians.
3.1.8.2 Vector Functions
The following are the functions which take one or more vector and float
parameters and return vector or float values. All of these functions support
only three component vectors. Assume that V1 and V2 are any valid expression
that evaluates to a three component vector and that A is any valid expression
that evaluates to a float.
vaxis_rotate(V1,V2,A): Rotate V1 about V2 by A. Given the x,y,z coordinates
of a point in space designated by the vector V1, rotate that point about an
arbitrary axis defined by the vector V2. Rotate it through an angle specified
in degrees by the float value A. The result is a vector containing the new
x,y,z coordinates of the point.
vcross(V1,V2): Cross product of V1 and V2. Returns a vector that is the
vector cross product of the two vectors. The resulting vector is
perpendicular to the two original vectors and its length is proportional to
the angle between them. See the animated demo scene VECT2.POV for an
illustration.
vdot(V1,V2): Dot product of V1 and V2. Returns a float value that is the dot
product (sometimes called scaler product of V1 with V2. Formula is
vdot=V1.x*V2.x + V1.y*V2.y + V1.z*V2.z. See the animated demo scene VECT2.POV
for an illustration.
vlength(V1): Length of V1. Returns a float value that is the length of vector
V1. Can be used to compute the distance between two points.
Dist=vlength(V2-V1). Formula is vlength=sqrt(vdot(V1,V1)).
vnormalize(V1): Normalize vector V1. Returns a unit length vector that is the
same direction as V1. Formula is vnormalize=V1/vlength(V1).
vrotate(V1,V2): Rotate V1 about origin by V2. Given the x,y,z coordinates of
a point in space designated by the vector V1, rotate that point about the
origin by an amount specified by the vector V2. Rotate it about the x-axis by
an angle specified in degrees by the float value V2.x. Similarly V2.y and
V2.z specify the amount to rotate in degrees about the y-axis and z-axis. The
result is a vector containing the new x,y,z coordinates of the point.
3.1.8.3 String Functions
The following are the functions which take one or more string and float
parameters and return string or float values. Assume that S1 and S2 are any
valid strings and that A L and P are any valid expressions that evaluate to
floats.
asc(S1): ASCII value of S1. Returns an integer value in the range 0 to 255
that is the ASCII value of the first character of S1. For example asc("ABC")
is 65 because that is the value of the character "A".
chr(A): Character whose ASCII value is A. Returns a single character string.
The ASCII value of the character is specified by an integer A which must be
in the range 0 to 255. For example chr(70) is the string "F".
concat(S1,S2,[S3...]): Concatenate strings S1 and S2. Returns a string that
is the concatenation of all parameter strings. Must have at least 2
parameters but may have more. For example:
concat("Value is ", str(A,3,1), " inches")
If the float value A was 12.34 the result is "Value is 12.3 inches" which is
a string.
file_exists(S1): Search for file specified by S1. Attempts to open the file
whose name is specified the string S1. The current directory and all
directories specified in any Library_Path INI options or +L command line
switches are searched. File is immediately closed. Returns a boolean value 1
on success and 0 on failure.
str(A,L,P): Convert float A to formatted string. Returns a formatted string
representation of float value A. The float parameter L specifies the minimum
length of the string and the type of left padding used if the string's
representation is shorter than the minimum. If L is positive then the padding
is with blanks. If L is negative then the padding is with zeros. The overall
minimum length of the formatted string is abs(L). If the string needs to be
longer, it will be made as long as necessary to represent the value.
The float parameter P specifies the number of digits after the decimal point.
If P is negative then a compiler-specific default precision is use. Here are
some examples:
str(123.456,0,3) "123.456"
str(123.456,4,3) "123.456"
str(123.456,9,3) " 123.456"
str(123.456,-9,3) "00123.456"
str(123.456,0,2) "123.46"
str(123.456,0,0) "123"
str(123.456,5,0) " 123"
str(123.000,7,2) " 123.00"
str(123.456,0,-1) "123.456000" (platform specific)
strcmp(S1,S2): Compare string S1 to S2. Returns a float value zero if the
strings are equal, a positive number if S1 comes after S2 in the ASCII
collating sequence, else a negative number.
strlen(S1): Length of S1. Returns an integer value that is the number of
characters in the string S1.
strlwr(S1): Lower case of S1. Returns a new string in which all upper case
letters in the string S1 are converted to lower case. The original string is
not affected. For example strlwr("Hello There!") results in "hello there!".
substr(S1,P,L): Sub-string from S1. Returns a string that is a subset of the
characters in parameter S1 starting at the position specified by the integer
value P for a length specified by the integer value L. For example
substr("ABCDEFGHI",4,2) evaluates to the string "EF". If P+L>strlen(S1) an
error occurs.
strupr(S1): Upper case of S1. Returns a new string in which all lower case
letters in the string S1 are converted to upper case. The original string is
not affected. For example strlwr("Hello There!") results in "HELLO THERE!".
val(S1): Convert string S1 to float. Returns a float value that is
represented by the text in S1. For example val("123.45") is 123.45 as a
float.
3.2 Language Directives
The POV Scene Language contains several statements called language directives
which tell the file parser how to do its job. These directives can appear in
almost any place in the scene file --- even in the middle of some other
statements. They are used to include other text files in the stream of
commands, to declare identifiers, to define conditional or looped parsing and
to control other important aspects of scene file processing.
Each directive begins with the hash character # (often called a number sign
or pound sign). It is followed by a keyword and optionally other parameters.
In versions of POV-Ray prior to 3.0, the use of this # character was
optional. Language directives could only be used between objects, camera or
light_source statements and could not appear within those statements. The
exception was the #include which could appear anywhere. Now that all language
directives can be used almost anywhere, the # character is mandatory.
The following keywords introduce language directives.
#break #default #statistics
#case #else #switch
#debug #end #version
#declare #render #warning
Earlier versions of POV-Ray considered #max_intersections and
#max_trace_level to be language directives but they have been moved to the
global_settings statement. Their use as a directive still works but it
generates a warning and may be discontinued in the future.
3.2.1 Include Files
The language allows include files to be specified by placing the line:
#include "filename.inc"
at any point in the input file. The filename may be specified by any valid
string expression but it usually is a literal string enclosed in double
quotes. It may be up to 40 characters long (or your computer's limit),
including the two double-quote (") characters.
The include file is read in as if it were inserted at that point in the file.
Using include is the same as actually cutting and pasting the entire contents
of this file into your scene.
Include files may be nested. You may have at most 10 nested include files.
There is no limit on un-nested include files.
Generally, include files have data for scenes, but are not scenes in
themselves. By convention scene files end in .pov and include files end with
.inc.
It is legal to specify drive and directory information in the file
specification however it is discouraged because it makes scene files less
portable between various platforms.
It is typical to put standard include files in a special sub-directory.
POV-Ray can only read files in the current directory or one referenced by the
Library_Path option (See section "Library Paths" ).
3.2.2 Declare
Identifiers may be declared and later referenced to make scene files more
readable and to parametrize scenes so that changing a single declaration
changes many values. There are several built-in identifiers which POV-Ray
declares for you. See "Built-in Identifiers" for details.
3.2.2.1 Declaring identifiers
An identifier is declared as follows.
#declare IDENTIFIER = ITEM
Where IDENTIFIER is the name of the identifier up to 40 characters long and
ITEM is any of the following:
float, vector, color or string expressions
objects (all kinds)
texture, pigment, normal, finish or halo
color_map, pigment_map, slope_map, normal_map
camera, light_source
atmosphere
fog
rainbow
skysphere
transform
Here are some examples.
#declare Rows = 5
#declare Count = Count+1
#declare Here = <1,2,3>
#declare White = rgb <1,1,1>
#declare Cyan = color blue 1.0 green 1.0
#declare Font_Name = "ariel.ttf"
#declare Ring = torus {5,1}
#declare Checks = pigment{ checker White, Cyan }
object{Rod scale y*5} // not "cylinder{Rod}"
object {
Ring
pigment {Checks scale 0.5}
transform Skew
}
Declarations, like most language directives, can appear anywhere in the file
--- even within other statements. For example:
#declare Here=<1,2,3>
#declare Count=0 // initialize Count
union {
object{Rod translate Here*Count}
#declare Count=Count+1 // re-declare inside union
object{Rod translate Here*Count}
#declare Count=Count+1 // re-declare inside union
object{Rod translate Here*Count}
}
As this example shows, you can re-declare an identifier and may use
previously declared values in that re-declaration. However if you attempt to
re-declare an identifier as anything other than its original type, it will
generate a warning message.
Declarations may be nested inside each other within limits. In the example in
the previous section you could declare the entire union as a object. However
for technical reasons you may not use any language directive inside the
declaration of floats, vectors or color expressions.
3.2.3 Default Directive
POV-Ray creates a default texture when it begins processing. You may change
those defaults as described below. Every time you specify a texture {...}
statement, POV-Ray creates a copy of the default texture. Anything you put in
the texture statement overrides the default settings. If you attach a
pigment, normal, or finish to an object without any texture statement then
POV-Ray checks to see if a texture has already been attached. If it has a
texture then the pigment, normal or finish will modify that existing texture.
If no texture has yet been attached to the object then the default texture is
copied and the pigment, normal or finish will modify that texture.
You may change the default texture, pigment, normal or finish using the
language directive #default {...} as follows:
#default {
texture {
pigment {...}
normal {...}
finish {...}
}
}
Or you may change just part of it like this:
#default {
pigment {...}
}
This still changes the pigment of the default texture. At any time there is
only one default texture made from the default pigment, normal and finish.
The example above does not make a separate default for pigments alone. Note:
Special textures tiles and material_map or a texture with a texture_map may
not be used as defaults.
You may change the defaults several times throughout a scene as you wish.
Subsequent #default statements begin with the defaults that were in effect at
the time. If you wish to reset to the original POV-Ray defaults then you
should first save them as follows:
//At top of file
#declare Original_Default = texture {}
later after changing defaults you may restore it with...
#default {texture {Original_Default}}
If you do not specify a texture for an object then the default texture is
attached when the object appears in the scene. It is not attached when an
object is declared. For example:
#declare My_Object=
sphere{<0,0,0>,1} // Default texture not applied
object{My_Object} // Default texture added here
You may force a default texture to be added by using an empty texture
statement as follows:
#declare My_Thing=
sphere{<0,0,0>,1 texture{}} // Default texture applied
The original POV-Ray defaults for all items are given throughout the
documentation under each appropriate section.
3.2.4 Version Directive
While many language changes have been made for POV-Ray 3.0, all of version
2.0 syntax and most of version 1.0 syntax still works. Whenever possible we
try to maintain backwards compatibility. One feature introduced in 2.0 that
was incompatible with any 1.0 scene files is the parsing of float
expressions. Setting +MV1.0 command line switch or the Version=1.0 INI option
turns off expression parsing as well as many warning messages so that nearly
all 1.0 files will still work. The changes between 2.0 and 3.0 are not as
extensive. Setting Version=2.0 is only necessary to eliminate some warning
messages. Naturally the default setting for this option is Version=3.0
The #version language directive is used to change modes within scene files.
This switch or INI options only affects the initial setting.
Together with the built-in version identifier, the #version directive allows
you to save and restore the previous values of this compatibility setting.
For example suppose MYSTUFF.INC is in version 1.0 format. At the top of the
file you could put:
#declare Temp_Vers = version // Save previous value
#version 1.0 // Change to 1.0 mode
... // Version 1.0 stuff goes here ...
#version Temp_Vers // Restore previous version
Previous versions of POV-Ray would not allow you to change versions inside an
object or declaration but that restriction has been lifted for POV-Ray 3.0.
Future versions of POV-Ray may not continue to maintain full backward
compatibility even with the #version directive. We strongly encourage you to
phase in 3.0 syntax as much as possible.
3.2.5 Conditional Directives
POV-Ray 3.0 allows a variety of new language directives to implement
conditional parsing of various sections of your scene file. This is
especially useful in describing the motion for animations but it has other
uses as well. Also available is a #while loop directive. You may nest
conditional directives 200 levels deep.
3.2.5.1 IF ELSE Directives
The simplest conditional directive is a traditional #if directive. It is of
the form...
#if (COND)
// This section is
// parsed if COND is true
#else
// This section is
// parsed if COND is false
#end // End of conditional part
where (COND) is a float expression that evaluates to a boolean value. A value
of 0.0 is false and any non-zero value is true. Note that extremely small
values of about 1e-10 are considered zero in case of round off errors. The
parentheses around the condition are required. The #else directive is
optional. The #end directive is required.
3.2.5.2 IFDEF Directives
The #ifdef directive is similar to the #if directive however it is used to
determine if an identifier has been previously declared. After the #ifdef
directive instead of a boolean expression you put a lone identifier enclosed
in parentheses. For example:
#ifdef (User_Thing)
// This section is parsed if the
// identifier "User_Thing" was
// previously declared
object{User_Thing} // invoke identifier
#else
// This section is parsed if the
// identifier "User_Thing" was not
// previously declared
box{<0,0,0>,<1,1,1>} // use a default
#end
// End of conditional part
3.2.5.3 SWITCH CASE & RANGE Directives
A more powerful conditional is the #switch directive. The syntax is as
follows...
#switch (VALUE)
#case (TEST_1)
// This section is parsed if VALUE=TEST_1
#break //First case ends
#case (TEST_2)
// This section is parsed if VALUE=TEST_2
#break //Second case ends
#range (LOW_1,HIGH_1)
// This section is parsed if (VALUE>=LOW_1)&(VALUE<=HIGH_1)
#break //Third case ends
#range (LOW_2,HIGH_2)
// This section is parsed if (VALUE>=LOW_2)&(VALUE<=HIGH_2)
#break //Fourth case ends
#else
// This section is parsed if no other case or
// range is true.
#end // End of conditional part
The float expression VALUE following the #switch directive is evaluated and
compared to the values in the #case or #range directives. When using #case,
it is followed by a float expression TEST_1 in parentheses. It is compared to
the VALUE. As usual in POV-Ray, float comparisons are considered equal if
their difference is under 1e-10. If the values are equal, parsing continues
normally until a #break, #else or #end directive is reached. If the
comparison fails, POV-Ray skips until another #case or #range is found.
If you use the #range directive, it is followed by two float expressions
LOW_1 and HIGH_1 which are enclosed in parentheses and separated by a comma.
If the switch VALUE is in the range specified, then parsing continues
normally until a #break, #else or #end directive is reached. If the VALUE is
outside the range, the comparison fails and POV-Ray skips until another #case
or #range is found.
If no #case or #range succeeds, the #else section is parsed. The #else
directive is optional. If no #else is specified and no match succeeds, then
parsing resumes after the #end directive.
There may be any number of #case or #range directives in any order you want.
If a segment evaluates true but no #break is specified, the parsing will fall
through to the next #case or #range and will continue until a #break, #else
or #end. Hitting a #break while parsing a successful section causes an
immediate jump to the #end without processing subsequent sections, even if a
subsequent condition would also have been satisfied.
3.2.5.4 WHILE Directive
The #while directive is a looping feature that makes it easy to place
multiple objects in a pattern or other uses. The #while directive is followed
by a float expression that evaluates to a boolean value. A value of 0.0 is
false and any non-zero value is true. Note that extremely small values of
about 1e-10 are considered zero in case of round off errors. The parentheses
around the expression are required. If the condition is true, parsing
continues normally until an #end directive is reached. At the end, POV-Ray
loops back to the #while directive and the condition is re-evaluated. Looping
continues until the condition fails. When it fails, parsing continues after
the #end directive. For example:
#declare Count=0
#while (Count < 5)
object{MyObject translate x*3*Count}
#declare Count=Count+1
#end
This example places five copies of MyObject in a row spaced three units apart
in the x direction.
3.2.6 User Message Directives
With the addition of conditional and loop directives, the POV-Ray language
has the potential to be more like an actual programming language. This means
that it will be necessary to have some way to see what is going on when
trying to debug loops and conditionals. To fulfill this need we have added
the ability to print text messages to the screen. You have a choice of five
different text streams to use including the ability to generate a fatal error
if you find it necessary. Limited formatting is available for strings output
by this method.
3.2.6.1 Text Message Streams
The syntax for a text message is any of the following:
#debug STRING
#error STRING
#fatal STRING
#render STRING
#statistics STRING
#warning STRING
Where STRING is any valid string of text including string identifiers or
functions which return strings.
For example:
#switch (clock*360)
#range (0,180)
#render "Clock in 0 to 180 range\n"
#break
#range (180,360)
#render "Clock in 180 to 360 range\n"
#break
#else
#warning "Clock outside expected range\n"
#warning concat("Value is:",str(clock*360,5,0),"\n")
#end
There are seven distinct text streams that POV-Ray uses for output. You may
output only to five of them. On some versions of POV-Ray, each stream is
designated by a particular color. Text from these streams are displayed
whenever it is appropriate so there is often an intermixing of the text. The
distinction is only important if you choose to turn some of the streams off
or to direct some of the streams to text files. On some systems you may be
able to review the streams separately in their own scroll-back buffer. See
"Console Text Output" for details on re-directing the streams to a text file.
Here is a description of how POV-Ray uses each stream. You may use them for
whatever purpose you want except note that use of the #fatal stream causes a
fatal error after the text is displayed.
DEBUG: This stream displays debugging messages. It was primarily designed for
developers but this and other streams may also be used by the user to display
messages from within their scene files.
FATAL: This stream displays fatal error messages. After displaying this text,
POV-Ray will terminate. When the error is a scene parsing error, you may be
shown several lines of scene text that leads up to the error.
RENDER: This stream displays information about what options you have
specified to render the scene. It includes feedback on all of the major
options such as scene name, resolution, animation settings, anti-aliasing and
others.
STATISTICS: This stream displays statistics after a frame is rendered. It
includes information about the number of rays traced, the length of time of
the processing and other information.
WARNING: This stream displays warning messages during the parsing of scene
files and other warnings. Despite the warning, POV-Ray can continue to render
the scene.
3.2.6.2 Text Formatting
Some escape sequences are available to include non-printing control
characters in your text. These sequences are similar to those used in string
literals in the C programming language. Note that these control characters
only apply in text message directives. They are not implemented for other
string usage in POV-Ray such as text objects or file names. Depending on what
platform you are using, they may not be fully supported for console output.
However they will appear in any text file if you re-direct a stream to a
file. The sequences are:
"\a" Bell or alarm, 0x07
"\b" Backspace, 0x08
"\f" Form feed, 0x0C
"\n" New line (line feed) 0x0A
"\r" Carriage return 0x0D
"\t" Horizontal tab 0x09
"\v" Vertical tab 0x0B
"\0" Null 0x00
"\\" Backslash 0x5C
"\'" Single quote 0x27
For example:
#debug "This is one line.\nBut this is another"
3.3 POV-Ray Coordinate System
Objects, lights, and the camera are positioned using a typical 3D coordinate
system. The usual coordinate system for POV-Ray has the positive Y axis
pointing up, the positive X axis pointing to the right, and the positive Z
axis pointing into the screen. The negative values of the axes point the
other direction, as follows:
^+Y
| /+Z
| /
| /
-X |/ +X
<-------|-------->
/|
/ |
/ |
-Z/ |
v-Y
The left-handed coordinate system.
Locations within that coordinate system are usually specified by a three
component vector. The three values correspond to the x, y and z directions
respectively. For example, the vector <1,2,3> means the point that's 1 unit
to the right, 2 units up, and 3 units in front the center of the "universe"
at <0,0,0>.
Vectors are not always points, though. They can also refer to an amount to
size, move, or rotate a scene element or to modify the texture pattern
applied to an object.
The supported transformations are rotate, scale, and translate. They are used
to turn, size, and translate an object or texture. A transformation matrix
may also be used to specify complex transformations directly.
3.3.1 Transformations
The supported transformations are rotate, scale, and translate. They are used
to turn, size, and translate an object or texture.
rotate <VECTOR>
scale <VECTOR>
translate <VECTOR>
3.3.1.1 Translate
An object or texture pattern may be moved by adding a translate parameter. It
consists of the keyword translate followed by a vector expression. The terms
of the vector specify the number of units to move in each of the x, y, and z
directions. Translate moves the element relative to it's current position.
For example
sphere { <10, 10, 10>, 1
pigment { Green }
translate <-5, 2, 1>
}
Will move the sphere from <10,10,10> to <-5,12,11>. It does not move it to
absolute location <-5,2,1>. Translating by zero will leave the element
unchanged on that axis. For example:
sphere { <10, 10, 10>, 1
pigment { Green }
translate 3*x // evaluates to <3,0,0> so move 3 units
// in the x direction and none along y or z
}
3.3.1.2 Scale
You may change the size of an object or texture pattern by adding a scale
parameter. It consists of the keyword scale followed by a vector expression.
The 3 terms of the vector specify the amount of scaling in each of the x, y,
and z directions.
Scale, is used to "stretch" or "squish" an element. Values larger than 1
stretch the element on that axis. Values smaller than one are used to squish
the element on that axis. Scale is relative to the current element size. If
the element has been previously re-sized using scale, then scale will size
relative to the new size. Multiple scale values may used.
For example:
sphere { <0,0,0>, 1
scale <2,1,0.5>
}
This stretches and smashes the sphere into an ellipsoid shape that is twice
the original size along the x direction, remains the same size in the y
direction, and is half the original size in the z direction.
If a lone float expression is specified, it is promoted to a 3 component
vector whose terms are all the same. Thus the item is uniformly scaled by the
same amount in all directions. For example:
object {
MyObject
scale 5 // Evaluates as <5,5,5> so uniformly scale
// by 5 in every direction.
}
3.3.1.3 Rotate
You may change the orientation of an object or texture pattern by adding a
rotate parameter. It consists of the keyword rotate followed by a vector
expression. The three terms of the vector specify the number of degrees to
rotate about each of the x, y, and z axes.
Note that the order of the rotations does matter. Rotations occur about the x
axis first, then the y axis, then the z axis. If you are not sure if this is
what you want then you should only rotate on one axis at a time using
multiple rotation statements to get a correct rotation. As in,
rotate <0, 30, 0> // 30 degrees around Y axis then,
rotate <-20, 0, 0> // -20 degrees around X axis then,
rotate <0, 0, 10> // 10 degrees around Z axis.
Rotation is always performed relative to the axis. Thus if an object is some
distance from the axis of rotation, its will not only rotate but it will
"orbit" about the axis as though it was swinging around on an invisible
string.
To work out the rotation directions, you must perform the famous "Computer
Graphics Aerobics" exercise. Hold up your left hand. Point your thumb in the
positive direction of the axis of rotation. Your fingers will curl in the
positive direction of rotation. Similarly if you point your thumb in the
negative direction of the axis your fingers will curl in the negative
direction of rotation. This is the famous "left-hand coordinate system".
^
+Y| +Z/ _
| /_| |_ _
| _| | | |/ \
| | | | | | |
| /| | | | | V
-X |/ | | | | | +X
<----------+--|-|-|-|-|------>
/| | \____
/ | | ___|
/ | \ /
/ | | /
-Z/ -Y|
/ |
"Computer Graphics Aerobics" to determine the rotation direction.
In this illustration, the left hand is curling around the x axis. The thumb
points in the positive x direction and the fingers curl over in the positive
rotation direction.
If you want to use a right hand system, as some CAD systems such as AutoCAD
do, the right vector in the camera specification needs to be changed. See the
detailed description of the camera. In a right handed system you use your
right hand for the "Aerobics".
Note: There is some controversy over whether POV-Ray's method of doing a
right-handed system is really proper. If you want to avoid problems we
suggest you stick with the left-handed system which is not in dispute.
3.3.1.4 Matrix Keyword
The matrix keyword can be used to explicitly specify the transformation
matrix to be used for objects or textures. Its syntax is:
matrix < M00, M01, M02,
M10, M11, M12,
M20, M21, M22,
M30, M31, M32 >
Where M00 through M32 are float expressions that specify the elements of a
4x4 matrix with the fourth column implicitly <0,0,0,1>. A point P=<px, py,
pz> is transformed into Q=(qx, qy, qz) by
qx = M00 * px + M10 * py + M20 * pz + M30
qy = M01 * px + M11 * py + M21 * pz + M31
qz = M02 * px + M12 * py + M22 * pz + M32
Normally you won't use the matrix keyword because it's less descriptive than
the transformation commands and harder to visualize. There is an intersecting
aspect of the matrix command though. It allows more general transformation
like shearing. The following matrix causes an object to be sheared along the
y axis.
object {
MyObject
matrix < 1, 1, 0,
0, 1, 0,
0, 0, 0,
0, 0, 0 >
}
3.3.2 Transformation Order
Because rotations are always relative to the axis and scaling is relative to
the origin, you will generally want to create an object at the origin and
scale and rotate it first. Then you may translate it into its proper
position. It is a common mistake to carefully position an object and then to
decide to rotate it. Because a rotation of an object causes it to orbit the
axis, the position of the object may change so much that it orbits out of the
field of view of the camera!
Similarly scaling after translation also moves an object unexpectedly. Ifyou
scale after you translate, the scale will multiply the translate amount. For
example:
translate <5, 6, 7>
scale 4
Will translate to 20, 24, 28 instead of 5, 6, 7. Be careful when transforming
to get the order correct for your purposes.
3.3.3 Transform Identifiers
At times it is useful to combine together several transformations and apply
them in multiple places. A transform identifier may be used for this purpose.
Transform identifiers are declared as follows:
#declare IDENT=transform { TRANSFORMATION... }
Where IDENT is the identifier to be declared and TRANSFORMATION is one or
more translate, rotate, scale or matrix specifications or a previously
declared transform identifier. A transform identifier is invoked by the
transform keyword without any brackets as shown here:
object {
MyObject // Get a copy of MyObject
transform MyTrans // Apply the transformation
translate -x*5 // Then move it 5 units left
}
object {
MyObject // Get another copy of MyObject
transform MyTrans // Apply the same transformation
translate -x*5 // Then move this one 5 units right
}
On extremely complex CSG objects with lots of components, it may speed up
parsing if you apply a declared transformation rather than the individual
translate, rotate, scale or matrix specifications. The transform is attached
just once to each component. Applying each individual translate, rotate,
scale or matrix specifications takes long. This only affects parsing ---
rendering works the same either way.
3.3.4 Transforming Textures and Objects
When an object is transformed, all textures attached to the object at that
time are transformed as well. This means that if you have a translate,
rotate, scale or matrix in an object before a texture, the texture will not
be transformed. If the transformation is after the texture then the texture
will be transformed with the object. If the transformation is inside the
texture {...} statement then only the texture is affected. The shape remains
the same. For example:
sphere { 0, 1
texture { Jade } // texture identifier from TEXTURES.INC
scale 3 // this scale affects both the
// shape and texture
}
sphere { 0, 1
scale 3 // this scale affects the shape only
texture { Jade }
}
sphere { 0, 1
texture {
Jade
scale 3 // this scale affects the texture only
}
}
Transformations may also be independently applied to pigment patterns and
surface normal (bump) patterns. Note scaling a normal pattern affects only
the width and spacing. It does not affect the apparent height or depth of the
bumps. For example:
box { <0, 0, 0>, <1, 1, 1>
texture {
pigment {
checker Red, White
scale 0.25 // This affects only the color pattern
}
normal {
bumps 0.3 // This specifies apparent height of bumps
scale 0.2 // Scales diameter and space between bumps
// but not the height. Has no effect on
// color pattern.
}
rotate y*45 // This affects the entire texture but
} // not the object.
}
3.4 Camera
The camera definition describes the position, projection type and properties
of the camera viewing the scene. Its syntax is:
camera {
[ perspective | orthographic | fisheye |
ultra_wide_angle | omnimax | panoramic |
cylinder FLOAT ]
location <VECTOR>
look_at <VECTOR>
right <VECTOR>
up <VECTOR>
direction <VECTOR>
sky <VECTOR>
right <VECTOR>
angle FLOAT
blur_samples FLOAT
aperture FLOAT
focal_point <VECTOR>
normal { NORMAL }
}
Depending on the projection type some of the parameters are required, some
are optional and some aren't used. If no projection type is given the
perspective projection will be used (pinhole camera). If no camera is
specified a default camera is used.
Regardless of the projection type all cameras use the "location", "look_at",
"right", "up", "direction", and "sky" keywords to determine the location and
orientation of the camera. Their meaning differs with the projection type
used. A more detailed explanation of the camera placement follows later.
3.4.1 Type of Projection
The following list explains the different projection types that can be used
with the camera. The most common types are the perspective and orthographic
projections.
Perspective projection: This projection represents the classic pinhole
camera. The viewing angle is either determined by the length of the direction
vector or by the optional keyword "angle". The viewing angle has to be larger
than 0 degrees and smaller than 180 degrees.
Orthographic projection: This projection uses parallel camera rays to create
an image of the scene. The size of the image is determined by the lengths of
the right and up vectors. The "angle" keyword isn't used with this
projection.
Fisheye projection: This is a spherical projection. The viewing angle is
specified by the "angle" keyword. An angle of 180 degrees creates the
"standard" fisheye while an angle of 360 degrees creates a super-fisheye
("I-see-everything-view"). If you use this projection you should get a
circular image. If this isn't the case, i.e. you get an elliptical image, you
should read "Aspect Ratio" .
Ultra wide angle projection: This projection is somewhat similar to the
fisheye but it projects the image onto a rectangle instead of a circle. The
viewing angle can be specified using the "angle" keyword.
Omnimax projection: The omnimax projection is a 180 degrees fisheye that has
a reduced viewing angle in the vertical direction. In reality this projection
is used to make movies that can be viewed in the dome-like Omnimax theaters.
The image will look somewhat elliptical. The "angle" keyword isn't used with
this projection.
Panoramic projection: This projection is called "cylindrical equirectangular
projection". It overcomes the degeneration problem of the perspective
projection if the viewing angle approaches 180 degrees. It uses some kind of
cylindrical projection to be able to use viewing angles larger than 180
degrees with a tolerable lateral-stretching distortion. The "angle" keyword
is used to determine the viewing angle.
Cylindrical projection: Using this projection the scene is projected onto a
cylinder. There are four different types of cylindrical projections depending
on the orientation of the cylinder and the position of the viewpoint. The
viewing angle and the length of the up or right vector determine the
dimensions of the camera and the visible image. The camera to use is
specified by a number. The types are:
1 vertical cylinder, fixed viewpoint
2 horizontal cylinder, fixed viewpoint
3 vertical cylinder, viewpoint moves along the cylinder's axis
4 horizontal cylinder, viewpoint moves along the cylinder's axis
The "angle" keyword overrides the viewing angle specified by the "direction"
keyword and vice versa.
There is no limitation to the viewing angle except for the perspective
projection. If you choose viewing angles larger than 360 degrees you'll see
repeated images of the scene (the way the repetition takes place depends on
the camera). This might be useful for special effects.
You should note that the vista buffer can only be used with the perspective
and orthographic camera.
3.4.2 Focal Blur
Simulates focal depth-of-field by shooting a number of sample rays from
jittered points within each pixel, and averaging the results.
The aperture setting determines the depth of the sharpness zone. Large
apertures give a lot of blurring, while narrow apertures will give a wide
zone of sharpness. Note that, while this behaves as a real camera does, the
values for aperture are purely arbitrary, and are not related to f-stops.
The center of the "zone of sharpness" is the focal_point vector (the default
focal_point is <0,0,0>).
The blur_samples value controls the maximum number of rays to use for each
pixel. More rays give a smoother appearance, but is slower, although this is
controlled somewhat by an adaptive mechanism that stops shooting rays when a
certain degree of confidence has been reached that shooting more rays would
not result in a significant change.
The confidence and variance variables control the adaptive function. The
confidence value is used to determine when the samples seem to be "close
enough" to the correct color. The variance value specifies an acceptable
tolerance on the variance of the samples taken so far. In other words, the
process of shooting sample rays is terminated when the estimated color value
is very likely (as controlled by the confidence probability) near the real
color value.
Since the confidence is a probability its values can range from 0 to 1 (the
default is 0.9, i.e. 90%). The value for the variance should be in the range
of the smallest displayable color difference (the default is 1/128).
Larger confidence values will lead to more samples, slower traces and better
images. The same holds for smaller variance thresholds.
By default no focal blur is used, i.e. the default aperture is 0 and the
default number of samples is 0.
3.4.3 Camera Ray Perturbation
The optional keyword "normal" may be used to assign a normal pattern to the
camera. All camera rays will be perturbed using this pattern. This lets you
create special effects. See animated scene CAMERA2.POV for an example.
3.4.4 Placing the Camera
In the following sections the placing of the camera will be further
explained.
3.4.4.1 Location and Look_At
Under many circumstances just two vectors in the camera statement are all you
need to position the camera: location and look_at. For example:
camera {
location <3,5,-10>
look_at <0,2,1>
}
The location is simply the X, Y, Z coordinates of the camera. The camera can
be located anywhere in the ray tracing universe. The default location is <0,
0, 0>. The look_at vector tells POV-Ray to pan and tilt the camera until it
is looking at the specified X, Y, Z coordinate. By default the camera looks
at a point one unit in the +Z direction from the location.
The look_at specification should almost always be the last item in the camera
statement. If other camera items are placed after the look_at vector then the
camera may not continue to look at the specified point.
3.4.4.2 The Sky Vector
Normally POV-Ray pans left or right by rotating about the Y axis until it
lines up with the look_at point and then tilts straight up or down until the
point is met exactly. However you may want to slant the camera sideways like
an airplane making a banked turn. You may change the tilt of the camera using
the "sky" vector. For example:
camera {
location <3,5,-10>
sky <1,1,0>
look_at <0,2,1>
}
This tells POV-Ray to roll the camera until the top of the camera is in line
with the sky vector. Imagine that the sky vector is an antenna pointing out
of the top of the camera. Then it uses the "sky" vector as the axis of
rotation left or right and then to tilt up or down in line with the "sky"
vector. In effect you're telling POV-Ray to assume that the sky isn't
straight up. Note that the sky vector must appear before the look_at vector.
The sky vector does nothing on its own. It only modifies the way the look_at
vector turns the camera. The default value for sky is <0, 1, 0>.
3.4.4.3 The Direction Vector
The "direction" vector tells POV-Ray the initial direction to point the
camera before moving it with look_at or rotate vectors. It may also be used
to control the field of view with some types of projection. This should be
done using the easier to use "angle" keyword though.
The default value is direction <0, 0, 1>
The length of the direction vector determines the field of view for the
perspective projection. It is the distance from the camera location to the
imaginary "view window" that you are looking through. A short direction
vector gives a wide angle view while a long direction gives a narrow,
telephoto view. You should be careful with small direction vector lengths,
i.e. large viewing angles. You may experience distortion on the edges of your
images. Objects will appear to be shaped strangely. If this happens, move the
location back and make the direction vector longer or decrease the viewing
angle.
If you are using the ultra wide angle, panoramic or cylindrical projection
you should use a unit length direction vector to avoid strange results.
The length of the direction vector doesn't matter if one of the following
projection types is used: orthographic, fisheye, or omnimax.
3.4.4.4 Up and Right Vectors
The direction of the "up" and "right" vectors (together with the direction
vector) determine the orientation of the camera in the scene. They are set
implicitly by their default values of
right 4/3*x
up y
or the "look_at" parameter (in combination with "location"). The directions
of an explicitly specified right and up vector will be overridden by any
following "look_at" parameter.
While some camera types ignore the length of these vectors others use it to
extract valuable information about the camera settings. The following list
will explain the meaning of the right and up vector for each camera type.
Since the direction the vectors is always used to describe the orientation of
the camera it will not be explained again.
Perspective projection: The lengths of the up and right vectors are used to
set the size of the viewing window and the aspect ratio as described in
detail in section "Aspect Ratio" . Since the field of view depends on the
length of the direction vector (implicitly set by the "angle" keyword or
explicitly set by the "direction" keyword) and the lengths of the right and
up vectors you should carefully choose them in order to get the desired
results.
Orthographic projection: The lengths of the right and up vector set the size
of the viewing window regardless of the direction vector length, which is not
used by the orthographic camera. Again the relation of the lengths is used to
set the aspect ratio.
Fisheye projection: The right and up vectors are used to set the aspect
ratio.
Ultra wide angle projection: The up and right vectors work in a similar way
as for the perspective camera.
Omnimax projection: The omnimax projection is a 180 degrees fisheye that has
a reduced viewing angle in the vertical direction. In reality this projection
is used to make movies that can be viewed in the dome-like Omnimax theaters.
The image will look somewhat elliptical. The "angle" keyword isn't used with
this projection.
Panoramic projection: The up and right vectors work in a similar way as for
the perspective camera.
Cylindrical projection: In cylinder type 1 and 3 the axis of the cylinder
lies along the "up" vector and the width is determined by the length of
"right" vector or it may be overridden with the "angle" vector. In type 3 the
"up" vector determines how many units high the image is. For example if you
have "up 4*y" on a camera at the origin. Only points from y=2 to y=-2 are
visible. All viewing rays are perpendicular to the y-axis. For type 2 and 4,
the cylinder lies along the "right" vector. Viewing rays for type 4 are
perpendicular to the "right" vector.
Note that the up, right, and direction vectors should always remain
perpendicular to each other or the image will be distorted. If this is not
the case a warning message will be printed.
3.4.4.4.1 Aspect Ratio
Together these vectors define the "aspect ratio" (height to width ratio) of
the resulting image. The default values "up <0, 1, 0>" and "right <1.33, 0,
0>" results in an aspect ratio of about 4 to 3. This is the aspect ratio of a
typical computer monitor. If you wanted a tall skinny image or a short wide
panoramic image or a perfectly square image you should adjust the up and
right vectors to the appropriate proportions.
Most computer video modes and graphics printers use perfectly square pixels.
For example Macintosh displays and IBM S-VGA modes 640x480, 800x600 and
1024x768 all use square pixels. When your intended viewing method uses square
pixels then the width and height you set with the +W and +H switches should
also have the same ratio as the right and up vectors. Note that 640/480 = 4/3
so the ratio is proper for this square pixel mode.
Not all display modes use square pixels however. For example IBM VGA mode
320x200 and Amiga 320x400 modes do not use square pixels. These two modes
still produce a 4/3 aspect ratio image. Therefore images intended to be
viewed on such hardware should still use 4/3 ratio on their up and right
vectors but the +W and +H settings will not be 4/3.
For example:
camera {
location <3,5,-10>
up <0,1,0>
right <1,0,0>
look_at <0,2,1>
}
This specifies a perfectly square image. On a square pixel display like SVGA
you would use +W and +H settings such as +W480 +H480 or +W600 +H600. However
on the non-square pixel Amiga 320x400 mode you would want to use values of
+W240 +H400 to render a square image.
3.4.4.4.2 Handedness
The "right" vector also describes the direction to the right of the camera.
It tells POV-Ray where the right side of your screen is. The sign of the
right vector can be used to determine the handedness of the coordinate system
in use. The default right statement is:
right <1.33, 0, 0>
This whole explanation needs work. DLR
The left-handed coordinate system.
This means that the +X direction is to the right. It is called a "left-
handed" system because you can use your left hand to keep track of the axes.
Hold out your left hand with your palm facing to your right. Stick your thumb
up. Point straight ahead with your index finger. Point your other fingers to
the right. Your bent fingers are pointing to the +X direction. Your thumb now
points +Y. Your index finger points +Z.
To use a right-handed coordinate system, as is popular in some CAD programs
and other ray tracers, make the same shape using your right hand. Your thumb
still points up in the +Y direction and your index finger still points
forward in the +Z direction but your other fingers now say the +X is to the
left. That means that the "right" side of your screen is now in the -X
direction. To tell POV-Ray to act like this this you can use a negative X
value in the "right" vector like this:
right <-1.33, 0, 0>
Since X increasing to the left doesn't make much sense on a 2D screen, you
now rotate the whole thing 180 degrees around by using a positive Z value in
your camera's location. You end up with something like this.
camera {
location <0,0,10>
up <0,1,0>
right <-1.33,0,0>
look_at <0,0,0>
}
Now when you do your ray tracer's aerobics, as explained in the section Scene
Basics "Rotate" , you use your right hand to determine the direction of
rotations.
In a 2 dimensional grid, X is always to the right and Y is up. The two
versions of handedness arise from the question of whether Z points into the
screen or out of it, and which axis in your computer model relates to up in
the real world.
Architectural CAD systems, like AutoCAD, tend to use the "God's Eye"
orientation that the Z axis is the elevation and is the model's up direction.
This approach makes sense if you're an architect looking at a building
blueprint on a computer screen. Z means up, and it increases towards you,
with X and Y still across and up the screen. This is the basic right handed
system.
Stand alone rendering systems, like POV-Ray, tend to consider you as a
participant. You're looking at the screen as if you were a photographer
standing in the scene. Up in the model is now Y, the same as up in the real
world, and X is still to the right, so Z must be depth, which increases away
from you into the screen. This is the basic left handed system.
3.4.4.5 Transforming the Camera
The "translate" and "rotate" commands can re-position the camera once you've
defined it.
For example:
camera {
location < 0, 0, 0>
direction < 0, 0, 1>
up < 0, 1, 0>
right < 1, 0, 0>
rotate <30, 60, 30>
translate < 5, 3, 4>
}
In this example, the camera is created, then rotated by 30 degrees about the
X axis, 60 degrees about the Y axis, and 30 degrees about the Z axis, then
translated to another point in space.
3.4.5 Camera Identifiers
You may declare several camera identifiers if you wish. This makes it easy to
quickly change cameras. For example:
#declare Long_Lens =
camera {
location -z*100
direction z*50
}
#declare Short_Lens =
camera {
location -z*50
direction z*10
}
camera {
Long_Lens //edit this line to change lenses
look_at Here
}
3.5 Objects
Objects are the building blocks of your scene. There are 20 different types
of objects supported by POV-Ray. Thirteen of them are finite solid
primitives, 4 are finite patch primitives, 5 are infinite solid polynomial
primitives, 3 are types of Constructive Solid Geometry and one is a
specialized object that is a light source.
The basic syntax of an object is a keyword describing its type, some floats,
vectors or other parameters which further define its location and/or shape
and some optional object modifiers such as texture, pigment, normal, finish,
bounding, clipping or transformations.
The texture describes what the object looks like, i. e. its material.
Textures are combinations of pigments, normals and finishes. Pigment is the
color or pattern of colors inherent in the material. Normal is a method of
simulating various patterns of bumps, dents, ripples or waves by modifying
the surface normal vector. Finish describes the reflective and refractive
properties of a material.
Bounding shapes are finite, invisible shapes which wrap around complex, slow
rendering shapes in order to speed up rendering time. Clipping shapes are
used to cut away parts of shapes to expose a hollow interior. Transformations
tell the ray tracer how to move, size or rotate the shape and/or the texture
in the scene.
3.5.1 Finite Solid Primitives
There are 13 different solid finite primitive shapes: blob, box, cone,
cylinder, fractal, height field, lathe, sphere, superellipsoid, surface of
revolution, text object and torus. These have a well-defined "inside" and can
be used in CSG (see section "Constructive Solid Geometry" ). They are finite
and respond to automatic bounding.
3.5.1.1 Blob
A blob. Blobs are an interesting and flexible object type. Mathematically
they are iso-surfaces of scalar fields, i.e. their surface is defined by the
strength of the field in each point. If this strength is equal to a threshold
value you're on the surface otherwise you're not.
Picture each blob component as an object floating in space. This object is
"filled" with a field that has its maximum at the center of the object and
drops off to zero at the object's surface. The field strength of all those
components are added together to form the field of the blob. Now POV-Ray
looks for points where this field has a given value, the "threshold" value.
All these points form the surface of the blob object. Points with a greater
field than the threshold value are considered to be inside while points with
a smaller field are outside.
There's another, simpler way of looking at blobs. They can be seen as a union
of "flexible" components that attract or repel each other to form a "blobby"
organic looking shape. The components' surfaces actually stretch out smoothly
and connect as if they were made of honey or something like that.
A blob is made up of spherical and cylindrical components and is defined as
follows:
blob {
threshold THRESHOLD_VALUE
cylinder { <END1>, <END2>, RADIUS, [ strength ] STRENGTH }
sphere { <CENTER>, RADIUS, [ strength ] STRENGTH }
[ component STRENGTH, RADIUS, <CENTER> ]
[ hierarchy FLAG ]
[ sturm ]
}
The threshold value is the total field strength value that POV-Ray is looking
for. By following the ray out into space and looking at how each blob
component affects the ray, POV-Ray will find the points in space where the
field strength is equal to the threshold value. The following list shows some
things you should know about the threshold value.
1) The threshold value must be positive.
2) A component disappears if the threshold value is greater than its
strength.
3) As the threshold value gets larger the surface you see gets closer to
the centers of the components.
4) As the threshold value gets smaller, the surface you see gets closer to
the surface of the components.
Cylindrical components are specified by the keyword "cylinder" giving a
cylinder formed by the base <END1>, the apex <END2> and the radius. This
cylinder has hemispherical caps at the base and apex. Spherical components
are specified by the keyword "sphere" forming a sphere at <CENTER> with the
gives radius. Each component can be individually translated, rotated, scaled
and textured. The complete syntax for the cylindrical and spherical
components is:
sphere { <CENTER>, RADIUS, [strength] STRENGTH
[ translate <VECTOR> ]
[ rotate <VECTOR> ]
[ scale <VECTOR> ]
TEXTURE_MODIFIERS
}
cylinder { <END1>, <END2>, RADIUS, [strength] STRENGTH
[ translate <VECTOR> ]
[ rotate <VECTOR> ]
[ scale <VECTOR> ]
TEXTURE_MODIFIERS
}
By unevenly scaling a spherical component you can create ellipsoidal
components. The component keyword gives a spherical component and is only
used for compatibility with earlier POV-Ray versions.
The "strength" parameter is a float value specifying the field strength at
the center of the object. The strength may be positive or negative. A
positive value will make that component attract other components while a
negative value will make it repel other components. Components in different,
separate blob shapes do not affect each other.
You should keep the following things in mind.
1) The strength value may be positive or negative. Zero is a bad value, as
the net result is that no field was added --- you might just as well
have not used this component.
2) If strength is positive, then POV-Ray will add the component's field to
the space around the center of the component. If this adds enough field
strength to be greater than the "threshold" value you will see a
surface.
3) If the strength value is negative, then POV-Ray will subtract the
component's field from the space around the center of the component.
This will only do something if there happen to be positive components
nearby. What happens is that the surface around any nearby positive
components will be dented away from the center of the negative
component.
The components of each blob object are internally bounded by a spherical
bounding hierarchy to speed up blob intersection tests and other operations.
By using the optional keyword "hierarchy" you can switch this hierarchy off.
An example of a three component blob is:
blob {
threshold 0.6
sphere { <.75, 0, 0>, 1, 1 }
sphere { <-.375, .64952, 0>, 1, 1 }
sphere { <-.375, -.64952, 0>, 1, 1 }
scale 2
}
If you have a single blob component then the surface you see will just look
like the object used, i.e. a sphere or a cylinder, with the surface being
somewhere inside the surface specified for the component. The exact surface
location can be determined from the blob equation listed below (you will
probably never need to know this, blobs are more for visual appeal than for
exact modeling).
For the more mathematically minded, here's the formula used internally by
POV-Ray to create blobs. You don't need to understand this to use blobs.
The formula used for a single blob component is:
density = strength * (1 - radius^2)^2
This formula has the nice property that it is exactly equal to STRENGTH at
the center of the component and drops off to exactly 0 at a distance of
RADIUS from the center of the component. The density formula for more than
one blob component is just the sum of the individual component densities:
density = density1 + density2 + ...
Blobs can be used in CSG shapes and they can be scaled, rotated and
translated. Because they are finite they respond to automatic bounding. The
calculations for blobs must be very accurate. If this shape renders
improperly you may add the keyword "sturm" after the last component to use
POV-Ray's slower-yet-more-accurate Sturmian root solver.
3.5.1.2 Box
A box. A simple box can be defined by listing two corners of the box like
this:
box {
<CORNER1>, <CORNER2>
}
Where <CORNER1> and <CORNER2> are vectors defining the x, y, z coordinates of
opposite corners of the box.
Note that all boxes are defined with their faces parallel to the coordinate
axes. They may later be rotated to any orientation using a rotate parameter.
Each element of CORNER1 should always be less than the corresponding element
in CORNER2. If any elements of CORNER1 are larger than CORNER2, the box will
not appear in the scene.
Boxes are calculated efficiently and make good bounding shapes. Because they
are finite they respond to automatic bounding. As with all shapes, they can
be translated, rotated and scaled.
3.5.1.3 Cone
A cone. A finite length cone or a frustum (a cone with the point cut off) may
be defined by.
cone {
<END1>, RADIUS1, <END2>, RADIUS2
}
Where <END1> and <END2> are vectors defining the x, y, z coordinates of the
center of each end of the cone and RADIUS1 and RADIUS2 are float values for
the radius of those ends.
Like a cylinder, normally the ends of a cone are closed by flat planes which
are parallel to each other and perpendicular to the length of the cone.
Adding the optional keyword "open" after RADIUS2 will remove the end caps and
results in a tapered hollow tube like a megaphone or funnel.
Because they are finite they respond to automatic bounding. As with all
shapes, they can be translated, rotated and scaled.
3.5.1.4 Cylinder
A cylinder. A finite length cylinder with parallel end caps may be defined
by.
cylinder {
<END1>, <END2>, RADIUS
}
Where <END1> and <END2> are vectors defining the x, y, z coordinates of the
center of each end of the cylinder and RADIUS is a float value for the
radius.
Normally the ends of a cylinder are closed by flat planes which are parallel
to each other and perpendicular to the length of the cylinder. Adding the
optional keyword "open" after the radius will remove the end caps and results
in a hollow tube.
Because they are finite they respond to automatic bounding. As with all
shapes, they can be translated, rotated and scaled.
3.5.1.5 Height Field
A height field. Height fields are fast, efficient objects that are generally
used to create mountains or other raised surfaces out of hundreds of
triangles in a mesh. The height field syntax is:
hfield {
FILE_TYPE "FILENAME"
[ hierarchy BOOL ]
[ smooth BOOL ]
[ water_level FLOAT ]
}
A height field is essentially a one unit wide by one unit long square with a
mountainous surface on top. The height of the mountain at each point is taken
from the color number or palette index of the pixels in a graphic image file.
The maximum height is one. That corresponds to the maximum possible color or
palette index value in the image file.
________ <---- image index 255 (or 65535 for 16-bit images)
/ /|
+1y ---------- |
| | |
| | |+1z <- Image upper-right
| | /
0,0,0---------- +1x
^
|____ Image lower-left
The size and orientation of an un-scaled height field.
The mesh of triangles corresponds directly to the pixels in the image file.
Each square formed by four neighboring pixels is divided into two triangles.
An image with a resolution of NxM pixels has (N-1)x(M-1) squares that are
divided into 2x(N-1)x(M-1) triangles.
The resolution of the height field is influenced by two factors: the
resolution of the image and the resolution of the color/index values. The
size of the image determines the resolution in the x- and z-direction. A
larger image uses more triangles and looks smoother. The resolution of the
color/index value determines the resolution along the y-axis. A height field
made from an 8 bit image can have 256 different height levels while one made
from a 16 bit image can have up to 65536 different height levels. Thus the
second height field will look much smoother in the y-direction if the height
field is created appropriately.
The size/resolution of the image does not affect the size of the height
field. The un-scaled height field size will always be 1x1. Higher resolution
image files will create smaller triangles, not larger height fields.
There are six or possibly seven types of files which can define a
heightfield, as follows:
height_field { gif "filename.gif" }
height_field { pgm "filename.pgm" }
height_field { png "filename.png" }
height_field { pot "filename.pot" }
height_field { ppm "filename.ppm" }
height_field { sys "filename.???" }
height_field { tga "filename.tga" }
The image file used to create a height field can be a GIF, TGA, POT, PNG,
PGM, PPM, and possibly a system specific (Windows BMP or Macintosh Pict)
format file. The GIF, PNG, PGM, and possibly system format files are the only
ones that can be created using a standard paint program. Though there are
paint programs for creating TGA image files they won't be of much use for
creating the special 16 bit TGA files used by POV-Ray (see below and
"HF_Gray_16" for more details).
In an image file like GIF that uses a color palette the color number is the
palette index at a given pixel. Use a paint program to look at the palette of
a GIF image. The first color is palette index zero, the second is index one,
the third is index two, and so on. The last palette entry is index 255.
Portions of the image that use low palette entries will result in lower parts
of the height field. Portions of the image that use higher palette entries
will result in higher parts of the height field.
Height fields created from GIF files can only have 256 different height
levels because the maximum number of colors in a GIF file is 256.
The color of the palette entry does not affect the height of the pixel. Color
entry 0 could be red, blue, black, or orange, but the height of any pixel
that uses color entry 0 will always be 0. Color entry 255 could be indigo,
hot pink, white, or sky blue, but the height of any pixel that uses color
entry 255 will always be 1.
You can create height field GIF images with a paint program or a fractal
program like "Fractint". You can usually get Fractint from most of the same
sources as POV-Ray.
A POT file is essentially a GIF file with a 16 bit palette. The maximum
number of colors in a POT file is 65536. This means a POT height field can
have up to 65536 possible height values. This makes it possible to have much
smoother height fields. Note that the maximum height of the field is still 1
even though more intermediate values are possible.
At the time of this writing, the only program that created POT files was a
freeware IBM-PC program called Fractint. POT files generated with this
fractal program create fantastic landscapes.
The TGA and PPM file formats may be used as a storage device for 16 bit
numbers rather than an image file. These formats use the red and green bytes
of each pixel to store the high and low bytes of a height value. These files
are as smooth as POT files, but they must be generated with special
custom-made programs. Several programs can create TGA heightfields in the
format POV uses, such as "gforge", and "Terrain Maker".
PNG format heightfields are usually stored in the form of a grayscale image,
with black corresponding to lower and white to higher parts of the height
field. Because PNG files can store up to 16 bits in grayscale images, they
will be as smooth as TGA and PPM images. Since they are grayscale images, you
will be able to view them with a regular image viewer. Gforge can create
16-bit heightfields in PNG format. Color PNG images will be used in the same
way as TGA and PPM images.
SYS format is a platform specific file format. See your platform specific
documentation for details.
An optional "water_level" parameter may be added after the file name. It
consists of the keyword "water_level" followed by a float value telling the
program to ignore parts of the height field below that value. The default
value is zero, and legal values are between zero and one. For example,
"water_level .5" tells POV-Ray to only render the top half of the height
field. The other half is "below the water" and couldn't be seen anyway. This
term comes from the popular use of height fields to render landscapes. A
height field would be used to create islands and another shape would be used
to
simulate water around the islands. A large portion of the height field would
be obscured by the "water" so the "water_level" parameter was introduced to
allow the ray-tracer to ignore the unseen parts of the height field.
Water_level is also used to "cut away" unwanted lower values in a height
field. For example, if you have an image of a fractal on a solid colored
background, where the background color is palette entry 0, you can remove the
background in the height field by specifying, "water_level .001"
Normally height fields have a rough, jagged look because they are made of
lots of flat triangles. Adding the keyword "smooth" causes POV-Ray to modify
the surface normal vectors of the triangles in such a way that the lighting
and shading of the triangles will give a smooth look. This may allow you to
use a lower resolution file for your height field than would otherwise be
needed. However, smooth triangles will take longer to render.
In order to speed up the intersection tests an one-level bounding hierarchy
is available. By default it is always used but it can be switched off to
eventually imrpove the rendering speed for small height fields (i.e. low
resolution images).
Height fields can be used in CSG shapes and they can be scaled, rotated and
translated. Because they are finite they respond to automatic bounding.
3.5.1.6 Julia Fractal
A julia fractal.
A julia fractal object is a 3-D slice of a 4-D object created by generalizing
the process used to create the classic Julia sets. You can make a wide
variety of strange objects using julia_fractal, including some that look like
bizarre blobs of twisted taffy.
The julia_fractal syntax (with default values listed in comments) is:
julia_fractal {
4DJULIA_PARAMETER // default is <1,0,0,0>
[ quaternion | hypercomplex ] // default is quaternion
[ sqr | cube | exp |
reciprocal | sin | asin |
sinh | asinh | cos | acos |
cosh | acosh | tan | atan |
tanh | atanh | log | pwr(X,Y) ] // default is sqr
[ max_iteration MAX_ITERATION ] // default value 20
[ precision PRECISION ] // default value 20
[ slice 4DNORMAL, DISTANCE ] // default <0,0,0,1>,0
}
The 4-D vector 4DJULIA_PARAMETER is the classic Julia parameter p in the
iterated formula f(h) + p.
The julia_fractal object is calculated by using an algorithm that determines
whether an arbitrary point h(0) in 4-D space is inside or outside the object.
The algorithm requires generating the sequence of vectors h(0), h(1), ... by
iterating the formula
h(n+1) = f(h(n)) + p (n = 0, 1, ..., max_iteration-1)
where p is the fixed 4-D vector parameter of julia_fractal, and f() is one of
the functions sqr, cube, ... specified by the presence of the corresponding
keyword. The point h(0) that begins the sequence is considered inside the
julia_fractal object if none of the vectors in the sequence escapes a
hypersphere of radius 4 about the origin before the iteration number reaches
the max_iteration value. As you increase the max_iteration, some points
escape that did not previously escape, making the julia_fractal. Depending on
the JULIA_PARAMETER, the julia_fractal object is not necessarily connected;
it may be scattered fractal "dust". Using a low max_iteration can fuse
together the dust to make a solid object. A high max_iteration is more
accurate but slows rendering. Even though it is not accurate, the solid
shapes you get with a low_maximum iteration value can be quite interesting.
Since the mathematical object described by this algorithm is
four-dimensional, and POV-Ray renders three dimensional objects, there must
be a way to reduce the number of dimensions of the object from four
dimensions to three. This is accomplished by intersecting the 4-D fractal
with a 3-D "plane" defined by the slice filed and then projecting the
intersection to 3-D space. The slice plane is the 3-D space that is
perpendicular to NORMAL4D and is DISTANCE units from the origin. Zero length
NORMAL4D vectors, or a NORMAL4D vector with a zero fourth component are
illegal.
You can get a good feel for the four dimensional nature of a julia_fractal by
using POV-Ray's animation feature to vary slice's DISTANCE parameter. You can
make the julia_fractal appear from nothing, grow, then shrink to nothing as
DISTANCE changes, much as the cross section of a 3-D object changes as it
passes through a plane.
The precision parameter is a tolerance used in the determination of whether
points are inside or outside the fractal object. Larger values give more
accurate results but slower rendering. Use as low a value as you can without
visibly degrading the fractal object's appearance.
The presence of the keywords quaternion or hypercomplex determine which 4-D
algebra is used to calculate the fractal. Both are 4-D generalizations of the
complex numbers but neither satisfies all the field properties (all the
properties of real and complex numbers that many of us slept through in high
school.) Quaternions have non-commutative multiplication, and hypercomplex
numbers can fail to have a multiplicative inverse for some non-zero elements.
(It has been proved that you cannot successfully generalize complex numbers
to four dimensions with all the field properties intact, so something has to
break.) Both of these algebras were discovered in the 19th century. Of the
two, the quaternions are much better known, but one can argue that
hypercomplex numbers are more useful for our purposes, since complex valued
functions such as sin, cos, etc. can be generalized to work for hypercomplex
numbers in a uniform way.
For the mathematically curious, the algebraic properties of these two
algebras can be derived from the multiplication properties of the unit basis
vectors 1 = <1,0,0,0>, i=<0,1,0,0>, j=<0,0,1,0>, and k=<0,0,0,1>. In both
algebras 1x = x1 = x for any x (1 is the multiplicative identity). The basis
vectors 1 and i behave exactly like the familiar complex numbers 1 and i in
both algebras.
Quaternion basis vector multiplication rules:
ij = k; jk = i; ki = j
ji = -k; kj = -i; ik = -j
ii = jj = kk = -1; ijk = -1;
Hypercomplex basis vector multiplication rules:
ij = k; jk = -i; ki = -j
ji = k; kj = -i; ik = -j
ii = jj = kk = -1; ijk = 1;
A distance estimation calculation is used with the quaternion calculations to
speed them up. The proof that this distance estimation formula works does not
generalize from two to four dimensions, but the formula seems to work well
anyway, the absence of proof notwithstanding!
The presence of one of the function keywords sqr, cube, etc. determine which
function is used for f(h) in the iteration formula h(n+1) = f(h(n)) + p. Most
of the function keywords work only if the hypercomplex keyword is present;
only sqr and cube work with quaternions. The functions are all familiar
complex functions generalized to four dimensions.
Function Keyword Maps 4-D value h to:
================================================
sqr h*h
cube h*h*h
exp e raised to the power h
reciprocal 1/h
sin sine of h
asin arcsine of h
sinh hyperbolic sine of h
asinh inverse hyperbolic sine of h
cos cosine of h
acos arccosine of h
cosh hyperbolic cos of h
acosh inverse hyperbolic cosine of h
tan tangent of h
atan arctangent of h
tanh hyperbolic tangent of h
atanh inverse hyperbolic tangent of h
log natural logarithm of h
pwr(x,y) h raised to the complex power x+iy
The first renderings of julia fractals using quaternions were done by Alan
Norton and later by John Hart in the '80's. This new POV-Ray implementation
follows Fractint in pushing beyond what is known in the literature by using
hypercomplex numbers and by generalizing the iterating formula to use a
variety of transcendental functions instead of just the classic Mandelbrot
"z^2 + c" formula. With an extra two dimensions and eighteen functions to
work with, intrepid explorers should be able to locate some new fractal
beasties in hyperspace, so have at it!
3.5.1.7 Lathe
A lathe. The lathe is an object generated from rotating a two-dimensional
curve about an axis. This curve is defined by a set of points which are
connected by linear, quadratic or cubic spline curves. The syntax is:
lathe {
[ linear_spline | quadratic_spline | cubic_spline ]
NUMBER_OF_POINTS,
<POINT_1>, <POINT_2>, ..., <POINT_n>
}
The parameter NUMBER_OF_POINTS determines how many two-dimensional points are
forming the curve. These points are connected by linear, quadratic or cubic
splines as specified by an optional keyword (the default is linear_spline).
Since the curve is not automatically closed, i.e. the first and last points
are not automatically connected, you'll have to do this by your own if you
want a closed curve. The curve thus defined is rotated about the y-axis to
form the lathe object which is centered at the origin.
The following examples creates a simple lathe object that looks like a
"thick" cylinder, i.e. a cylinder with a thick wall:
lathe {
linear_spline
5,
<2, 0>, <3, 0>, <3, 5>, <2, 5>, <2, 0>
pigment {Red}
}
The cylinder has an inner radius of 2 and an outer radius of 3, giving a wall
width of 1. It's height is 5 and it's located at the origin pointing up, i.e.
the rotation axis is the y-axis. Note that the first and last point are equal
to get a closed curve.
The splines that are used by the lathe and prism objects are a little bit
difficult to understand. The basic concept of splines is to draw a curve
through a given set of points in a determined way. The linear spline is the
simplest spline because it's nothing more than connecting consecutive points
with a line. This means that the curve that is drawn between two points only
depends on those two points. No additional information is taken into account.
Quadratic and cubic splines are different in that they do not only take other
points into account when connecting two points but they also look smoother
and - in the case of the cubic spline - produce smoother transitions at each
point.
Quadratic splines are made of quadratic curves. Each of them connects two
consecutive points. Since those two points (call them second and third point)
aren't enough to describe a quadratic curve the predecessor of the third
point is taken into account when the curve is drawn. Mathematically the
relationship (their location on the 2-D plane) between the third and fourth
point determines the slope of the curve at the third point. The slope of the
curve at the second point is out of control. Thus quadratic splines look much
"smoother" than linear splines but the transitions at each point are
generally not smooth because the slopes on "both sides" of the point are
different.
Cubic splines overcome the transition problem of quadratic splines because
they also take the first point into account when drawing the curve between
the second and third point. The slope at the second point is under control
now and allows a smooth transition at each point. Thus cubic splines produce
the most flexible and smooth curves.
You should note that the number of spline segments, i.e. curves between two
points, depends on the spline type used. For linear splines you get n-1
segments connecting the points P[i], i=1...n. A quadratic spline gives you
n-2 segments because the last point is only used for determining the slope as
explained above (thus you'll need at least three points to define a quadratic
spline). The same holds for cubic splines where you get n-3 segments with the
first and last point used only for slope calculations (thus needing at least
four points).
If you want to get a closed quadratic and cubic spline with smooth
transitions at the end points you have to make sure that in the cubic case
P[n-1] = P[2] (to get a closed curve), P[n] = P[3] and P[n-2] = P[1] (to
smooth the transition). In the quadratic case P[n-1] = P[1] (to close the
curve) and P[n] = P[2].
Lathe objects respond to automatic bounding and can be translated, rotated
and scaled.
3.5.1.8 Prism
A prism. The prism is an object generated from sweeping a two-dimensional,
closed curve along an axis. This curve is defined by a set of points which
are connected by linear, quadratic or cubic splines. The syntax is:
prism {
[ linear_sweep | conic_sweep ]
[ linear_spline | quadratic_spline | cubic_spline ]
HEIGHT1,
HEIGHT2,
NUMBER_OF_POINTS,
<POINT_1>, <POINT_2>, ..., <POINT_n>
[ open ]
[ sturm ]
}
The parameter NUMBER_OF_POINTS determines how many two-dimensional points are
forming the curve. These points, which are given in the x-z-plane, are
connected by linear, quadratic or cubic splines as specified by an optional
keyword (the default is linear spline) to get a closed curve. It is swept
along the y-axis from HEIGHT1 to HEIGHT2 to form the prism object. By default
linear sweeping is used to create the prism, i.e. the prism's walls are
perpendicular to the x-z-plane (the size of the curve doesn't change during
the sweep). You can also use conic sweeping that leads to a prism with
"cone-like" walls by scaling the curve down during the sweep.
Like cylinders the prism is normally closed. You can remove the caps on the
prism by using the "open" keyword. If you do so you shouldn't use it with CSG
because the results may get wrong.
The following example creates a simple prism object that looks like a piece
of cake:
prism {
linear_sweep
linear_spline
0, 1,
3,
<-1, 0>, <1, 0>, <0, 5>
pigment {Red}
}
For an explanation of the spline concept read the description of the lathe
object.
Prism objects respond to automatic bounding and can be translated, rotated
and scaled.
3.5.1.9 Sphere
A sphere. The syntax of the sphere object is:
sphere {
<CENTER>, RADIUS
}
Where <CENTER> is a vector specifying the x, y, z coordinates of the center
of the sphere and RADIUS is a float value specifying the radius. Spheres may
be scaled unevenly giving an ellipsoid shape.
Because spheres are highly optimized they make good bounding shapes. Because
they are finite they respond to automatic bounding. As with all shapes, they
can be translated, rotated and scaled.
3.5.1.10 Superquadric Ellipsoid
A superquadric ellipsoid. The superquadric ellipsoid is an extension of the
quadric ellipsoid. It can be used to create boxes and cylinders with round
edges and other interesting shapes. Mathematically it is given by the
equation:
f(x, y, z) = (|x|^(2/e) + |y|^(2/e)) ^ (e/n) + |z|^(2/n) - 1 = 0
The values of e and n, called the east-west and north-south exponent,
determine the shape of the superquadric ellipsoid. Both have to be greater
than zero. The sphere is e.g. given by e = 1 and n = 1.
The syntax of the superquadric ellipsoid is:
superellipsoid { <e, n> }
The object is located at the origin and can be translated, rotated and scaled
just like any other object. Since it is finite it responds to automatic
bounding.
Two useful objects are the rounded box and the rounded cylinder. These are
declared in the following way.
#declare Rounded_Box = superellipsoid { <r, r> }
#declare Rounded_Cylinder = superellipsoid { <1, r> }
The roundedness r determines the roundedness of the edges and has to be
greater than zero and smaller than one. The smaller you choose the values of
r the smaller and sharper the edges will get.
3.5.1.11 Surface of Revolution
A surface of revolution. The surface of revolution (SOR) object is generated
by rotating a line about an axis. This line is essentially a function
describing the dependence of the radius from the position on the rotation
axis.
The syntax of the SOR object is:
sor {
NUMBER_OF_POINTS,
<POINT1>, <POINT2>, ..., <POINTn>
[ open ]
}
The points <POINT1> through <POINTn> are two dimensional vectors consisting
of the radius and the corresponding position on the rotation axis. These
points are smoothly connected and rotated about the y-axis to form the SOR
object. The first and last points are only used to determine the slopes of
the function at the start and end point. The function used for the SOR object
is similar to the splines used for the lathe object. The difference is that
the SOR object is less flexible because it underlies the restrictions of any
mathematical function, i.e. to any given point y on the rotation axis
corresponds at most one radius. You can't rotate closed curves with the SOR
object.
The optional keyword "open" allows you to remove the caps on the SOR object.
If you do this you shouldn't use it with CSG anymore because the results may
be wrong.
The SOR object is useful for creating bottles, vases, and things like that. A
simple vase could look like this:
#declare Vase = sor {
7,
<0.000000, 0.000000>
<0.118143, 0.000000>
<0.620253, 0.540084>
<0.210970, 0.827004>
<0.194093, 0.962025>
<0.286920, 1.000000>
<0.468354, 1.033755>
open
}
One might ask why there is any need for a SOR object if there is already a
lathe object which is much more flexible. The reason is quite simple. The
intersection test with a SOR object involves solving of a cubic polynomial
while the test with a lathe object requires solution of a 6th order
polynomial (you need a cubic spline for the same "smoothness"). Since most
SOR and lathe objects will have several segments this will make a great
difference in speed. The roots of the 3rd order polynomial will also be more
accurate and easier to find.
Surface of revolution objects respond to automatic bounding and can be
translated, rotated and scaled.
3.5.1.12 Text
A text object. A text object creates 3-D text as an extruded block letter.
Currently only TrueType fonts are supported but the syntax allows for other
font types to be added in the future. The syntax is:
text {
ttf "FONTNAME.TTF",
"STRING_OF_TEXT",
THICKNESS_FLOAT, OFFSET_VECTOR
}
Where FONTNAME.TTF is the name of the TrueType font file. It is a quoted
string literal or string expression. The string expression which follows is
the actual text of the string object. It too may be a quoted string literal
or string expression. See "Strings" for more on string expressions.
The text will start with the origin at the lower, left, front of the first
character and will extend in the +x direction. The baseline of the text
follows the x-axis and decenders drop into the -y direction. The front of the
character sits in the X-Y plane and the text is extruded in the +z direction.
The front-to-back thickness is specified by the required value
THICKNESS_FLOAT.
Characters are generally sized so that 1 unit of vertical spacing is correct.
The characters are about 0.5 to 0.75 units tall.
The horizontal spacing is handled by POV-Ray internally including any kerning
information stored in the font. The required vector OFFSET_VECTOR defines any
extra translation between each character. Normally you should specify a zero
for this value. Specifing 0.1*x would put additional 0.1 units of space
between each character.
Only printable characters are allowed in text objects. Characters such as
return, line feed, tabs, backspace etc. are not supported.
3.5.1.13 Torus
A torus. A torus is a 4th order quartic polynomial shape that looks like a
donut or inner tube. Because this shape is so useful and quartics are
difficult to define, POV-Ray lets you take a short-cut and define a torus by:
torus {
MAJOR, MINOR
[ sturm ]
}
where MAJOR is a float value giving the major radius and MINOR is a float
specifying the minor radius. The major radius extends from the center of the
hole to the mid-line of the rim while the minor radius is the radius of the
cross-section of the rim. The torus is centered at the origin and lies in the
X-Z plane with the Y-axis sticking through the hole.
----------- - - - - - - - ---------- +Y
/ \ / \ |
/ \ / \ |
| | | |<-B-->| -X---|---+X
\ / \ / |
\__________/_ _ _ _ _ _ _ \__________/ |
|<-----A----->| -Y
A = Major Radius
B = Minor Radius
Major & Minor Radius.
The torus is internally bounded by two cylinders and two rings forming a
"thick" cylinder. With this bounding cylinder the performance of the torus
intersection test is vastly increased. The test for a valid torus
intersection, i.e. solving a 4th order polynomial, is only performed if the
bounding cylinder is hit. Thus a lot of slow root solving calculations are
avoided.
Calculations for all higher order polynomials must be very accurate. If the
torus renders improperly you may add the keyword "sturm" after the MINOR
value to use POV-Ray's slower-yet-more-accurate Sturmian root solver.
3.5.2 Finite Patch Primitives
There are 6 totally thin, finite objects which have no well-defined inside.
They may be combined in CSG union but cannot be use in other types of CSG.
They are bicubic patch, disc, smooth triangle, triangle, polygon, and mesh.
Because these types are finite, POV-Ray can use automatic bounding on them to
speed up rendering time.
3.5.2.1 Bicubic patch
A teapot made of bezier patches. A bicubic patch is a 3D curved surface
created from a mesh of triangles. POV-Ray supports a type of bicubic patch
called a Bezier patch. A bicubic patch is defined as follows:
bicubic_patch {
type PATCH_TYPE
flatness FLATNESS_VALUE
u_steps NUM_U_STEPS
v_steps NUM_V_STEPS
<CP1>, <CP2>, <CP3>, <CP4>,
<CP5>, <CP6>, <CP7>, <CP8>,
<CP9>, <CP10>, <CP11>, <CP12>,
<CP13>, <CP14>, <CP15>, <CP16>
}
The keyword "type" is followed by a float PATCH_TYPE which currently must be
either 0 or 1. For type 0 only the control points are retained within
POV-Ray. This means that a minimal amount of memory is needed, but POV-Ray
will need to perform many extra calculations when trying to render the patch.
Type 1 preprocesses the patch into many subpatches. This results in a
significant speedup in rendering, at the cost of memory.
These four parameters: type, flatness, u_steps & v_steps, may appear in any
order. They are followed by 16 vectors that define the x, y, z coordinates of
the 16 control points which define the patch. The patch touches the four
corner points <CP1>, <CP4>, <CP13> and <CP16> while the other 12 points pull
and stretch the patch into shape.
The keywords "u_steps" and "v_steps" are each followed by float values which
tell how many rows and columns of triangles are the minimum to use to create
the surface. The maximum number of individual pieces of the patch that are
tested by POV-Ray can be calculated from the following:
sub-pieces = 2^u_steps * 2^v_steps
This means that you really should keep "u_steps" and "v_steps" under 4 or
Most patches look just fine with "u_steps 3" and "v_steps 3", which
translates to 64 subpatches (128 smooth triangles).
As POV-Ray processes the Bezier patch, it makes a test of the current piece
of the patch to see if it is flat enough to just pretend it is a rectangle.
The statement that controls this test is: "flatness xxx". Typical flatness
values range from 0 to 1 (the lower the slower).
If the value for flatness is 0, then POV-Ray will always subdivide the patch
to the extend specified by u_steps and v_steps. If flatness is greater than
0, then every time the patch is split, POV-Ray will check to see if there is
any need to split further.
There are both advantages and disadvantages to using a non-zero flatness. The
advantages include:
- If the patch isn't very curved, then this will be detected and POV-Ray
won't waste a lot of time looking at the wrong pieces.
- If the patch is only highly curved in a couple of places, POV-Ray will
keep subdividing there and concentrate it's efforts on the hard part.
The biggest disadvantage is that if POV-Ray stops subdividing at a particular
level on one part of the patch and at a different level on an adjacent part
of the patch, there is the potential for "cracking". This is typically
visible as spots within the patch where you can see through. How bad this
appears depends very highly on the angle at which you are viewing the patch.
Like triangles, the bicubic patch is not meant to be generated by hand. These
shapes should be created by a special utility. You may be able to acquire
utilities to generate these shapes from the same source from which you
obtained POV-Ray.
bicubic_patch {
type 1
flatness 0.01
u_steps 4
v_steps 4
<0, 0, 2>, <1, 0, 0>, <2, 0, 0>, <3, 0,-2>,
<0, 1 0>, <1, 1, 0>, <2, 1, 0>, <3, 1, 0>,
<0, 2, 0>, <1, 2, 0>, <2, 2, 0>, <3, 2, 0>,
<0, 3, 2>, <1, 3, 0>, <2, 3, 0>, <3, 3, -2>
}
The triangles in a POV-Ray bicubic_patch are automatically smoothed using
normal interpolation but it is up to the user (or the user's utility program)
to create control points which smoothly stitch together groups of patches.
As with the other shapes, bicubic_patch objects can be translated, rotated,
and scaled. Because they are finite they respond to automatic bounding. Since
it's made from triangles, a bicubic_patch cannot be used in CSG intersection
or difference types or inside a clipped_by modifier because triangles have no
clear "inside". The CSG union type works acceptably.
3.5.2.2 Disc
A disc. One other flat, finite object type is available with POV-Ray. Note
that a disc is infinitely thin. It has no thickness. If you want a disc with
true thickness you should use a very short cylinder. A disc shape may be
defined by:
disc {
<CENTER>, <NORMAL>, RADIUS [, HOLE_RADIUS ]
}
The vector <CENTER> defines the x, y, z coordinates of the center of the
disc. The <NORMAL> vector describes its orientation by describing its surface
normal vector. This is followed by a float specifying the RADIUS. This may be
optionally followed by another float specifying the radius of a hole to be
cut from the center of the disc.
As with the other shapes, discs can be translated, rotated, and scaled.
Because they are finite they respond to automatic bounding. Disc cannot be
used in CSG intersection or difference types or inside a clipped_by modifier
because it has no clear "inside". The CSG union type works acceptably.
3.5.2.3 Mesh
A triangle mesh. The mesh object can be used to efficiently trace meshes of
hundreds or thousands of triangles. Its syntax is:
mesh {
triangle {
<CORNER1>, <CORNER2>, <CORNER3>
[ texture { STRING } ]
}
smooth_triangle {
<CORNER1>, <NORMAL1>,
<CORNER2>, <NORMAL2>,
<CORNER3>, <NORMAL3>
[ texture { STRING } ]
}
[ hierarchy FLAG ]
}
Any number of triangles and/or smooth triangles can be used and each of those
triangles can be individually textured by assigning a texture name to it. The
texture has to be declared before the mesh is parsed. It is not possible to
use texture definitions inside the triangle or smooth triangle statements.
This is a restriction that is necessary for an efficient storage of the
assigned textures.
The mesh's components are internally bounded by a bounding box hierarchy to
speed up intersection testing. The bounding hierarchy can be turned off with
the "hierarchy" keyword. This should only be done if memory is short or the
mesh consists of only a few triangles.
Copies of a mesh object refer to the same triangle data and thus consume very
little memory. You can easily trace hundred copies of a 10000 triangle mesh
without running out of memory (assuming the first mesh fits into memory).
The mesh object can currently only include triangle and smooth triangle
components. That restriction is liable to change, allowing polygonal
components, at some point in the future.
Meshes are finite and respond to automatic bounding. As with all shapes, they
can be translated, rotated and scaled. They can only be used with CSG unions.
3.5.2.4 Polygon
A polygon. Polygons are useful for creating rectangles, squares, and other
planar shapes with more than three edges (you'd use a triangle for this).
The polygon syntax is:
polygon {
NUMBER_OF_POINTS,
<POINT_1>, <POINT_2>, ..., <POINT_n>
}
The points <POINT1> through <POINTn> are two dimensional vectors describing
the shape of the polygon in the xy plane. You enter two values for each
coordinate, and the program assumes that the z value is always zero. Place
the polygon at its final location using rotate and translate. The polygon is
automatically closed so there's no need for setting <POINTn> = <POINT1>.
A square polygon that matches the default planar imagemap is simply:
polygon {
4,
<0, 0>, <0, 1>, <1, 1>, <1, 0>
texture {
finish { ambient 1 diffuse 0 }
pigment { image_map { gif "test.gif" } }
}
//scale and rotate as needed here
}
A complex example for a polygon is the letter "P":
#declare P = polygon {
12,
<0, 0>, <0, 6>, <4, 6>, <4, 3>, <1, 3>, <1, 0>, <0, 0>,
<1, 4>, <1, 5>, <3, 5>, <3, 4>, <1, 4>
}
This polygon is actually made up of two polygons. The first one (on the first
line) describes the outer shape of the letter "P". The second polygon (on the
second line) describes the rectangular hole that is cut in the top of the
letter "P". Note that in this case both rectangles have to be closed, i.e.
their first and last points have to be the same. You can cut more than one
hole in any polygon if you make sure that all polygons that are used for the
holes are inside the polygon you are cutting from and that they do not
overlapp.
The feature of cutting holes into a polygon is based on the polygon
inside/outside test used. A point is considerd to be inside a polygon if a
straight line drawn from this point in an arbitrary direction crosses an odd
number of edges (this is known as Jordan's curve theorem). Based on that
knowledge it is also possible to cut more than one hole in a polygon. This is
something to experiment with.
Polygons respond to automatic bounding and can be translated, rotated and
scaled.
3.5.2.5 Triangle and smooth triangle
A triangle. The triangle primitive is available in order to make more complex
objects than the built-in shapes will permit. Triangles are usually not
created by hand, but are converted from other files or generated by
utilities.
A triangle is defined by:
triangle {
<CORNER1>, <CORNER2>, <CORNER3>
}
where <CORNERn> is a vector defining the x, y, z coordinates of each corner
of the triangle.
Because triangles are perfectly flat surfaces it would require extremely
large numbers of very small triangles to approximate a smooth, curved
surface. However much of our perception of smooth surfaces is dependent upon
the way light and shading is done. By artificially modifying the surface
normals we can simulate as smooth surface and hide the sharp-edged seams
between individual triangles.
The smooth triangle primitive is used for just such purposes. The smooth
triangles use a formula called Phong normal interpolation to calculate the
surface normal for any point on the triangle based on normal vectors which
you define for the three corners. This makes the triangle appear to be a
smooth curved surface. A smooth triangle is defined by:
smooth_triangle {
<CORNER1>, <NORMAL1>,
<CORNER2>, <NORMAL2>,
<CORNER3>, <NORMAL3>
}
where the corners are defined as in regular triangles and <NORMALn> is a
vector describing the direction of the surface normal at each corner.
These normal vectors are prohibitively difficult to compute by hand.
Therefore smooth triangles are almost always generated by utility programs.
To achieve smooth results, any triangles which share a common vertex should
have the same normal vector at that vertex. Generally the smoothed normal
should be the average of all the actual normals of the triangles which share
that point.
3.5.3 Infinite Solid Primitives
There are 5 polynomial primitive shapes that are possibly infinite and do not
respond to automatic bounding. They do have a well defined inside and may be
used in CSG. They are plane, cubic, poly, quadric, and quartic.
3.5.3.1 Plane
The plane primitive is a simple way to define an infinite flat surface. The
plane is specified as follows:
plane { <NORMAL>, DISTANCE }
The <NORMAL> vector defines the surface normal of the plane. A surface normal
is a vector which points up from the surface at a 90 degree angle. This is
followed by a float value that gives the distance along the normal that the
plane is from the origin. For example:
plane { <0,1,0>,4 }
This is a plane where "straight up" is defined in the positive y direction.
The plane is 4 units in that direction away from the origin. Because most
planes are defined with surface normals in the direction of an axis, you will
often see planes defined using the "x", "y", or "z" built-in vector
identifiers. The example above could be specified as:
plane { y,4 }
The plane extends infinitely in the x and z directions. It effectively
divides the world into two pieces. By definition the normal vector points to
the outside of the plane while any points away from the vector are defined as
inside. This inside/outside distinction is only important when using planes
in CSG.
As with the other shapes, planes can be translated, rotated, and scaled.
Because they are infinite they do not respond to automatic bounding. Planes
can be used freely in CSG because they have a clear defined "inside".
A plane is called a "polynomial" shape because it is defined by a first order
polynomial equation. Given a plane:
plane { <A, B, C>, D }
it can be represented by the equation:
A*x + B*y + C*z - D = 0
Therefore our example "plane {y,4}" is actually the polynomial equation
"y=4". You can think of this as a set of all x,y,z points where all have y
values equal to 4, regardless of the x or z values.
This equation is a "first order" polynomial because each term contains only
single powers of x, y or z. A second order equation has terms like x^2, y^2,
z^2, xy, xz and yz. Another name for a 2nd order equation is a quadric
equation. Third order polys are called cubics. A 4th order equation is a
quartic. Such shapes are described in the sections below.
3.5.3.2 Poly, Cubic and Quartic
A quartic surface (quartic cylinder). Higher order polynomial surfaces may be
defined by the use of a poly shape. The syntax is:
poly { ORDER, <T1, T2, T3, .... Tm> }
Where ORDER is a whole number from 2 to 7 inclusively that specifies the
order of the equation. T1, T2... Tm are float values for the coefficients of
the equation. There are "m" such terms where
m = ((ORDER+1)*(ORDER+2)*(ORDER+3))/6
An alternate way to specify 3rd order polys is:
cubic { <T1, T2,... T20> }
Also 4th order equations may be specified with:
quartic { <T1, T2,... T35> }
Here's a more mathematical description of quartics for those who are
interested. Quartic surfaces are 4th order surfaces, and can be used to
describe a large class of shapes including the torus, the lemniscate, etc.
The general equation for a quartic equation in three variables is (hold onto
your hat):
a00 x^4 + a01 x^3 y + a02 x^3 z+ a03 x^3 + a04 x^2 y^2+
a05 x^2 y z+ a06 x^2 y + a07 x^2 z^2+a08 x^2 z+a09 x^2+
a10 x y^3+a11 x y^2 z+ a12 x y^2+a13 x y z^2+a14 x y z+
a15 x y + a16 x z^3 + a17 x z^2 + a18 x z + a19 x+
a20 y^4 + a21 y^3 z + a22 y^3+ a23 y^2 z^2 +a24 y^2 z+
a25 y^2 + a26 y z^3 + a27 y z^2 + a28 y z + a29 y+
a30 z^4 + a31 z^3 + a32 z^2 + a33 z + a34 = 0
To declare a quartic surface requires that each of the coefficients (a0 ->
a34) be placed in order into a single long vector of 35 terms.
As an example let's define a torus the hard way. A Torus can be represented
by the equation:
x^4 + y^4 + z^4 + 2 x^2 y^2 + 2 x^2 z^2 + 2 y^2 z^2 -
2 (r0^2 + r1^2) x^2 + 2 (r0^2 - r1^2) y^2 -
2 (r0^2 + r1^2) z^2 + (r0^2 - r1^2)^2 = 0
Where r0 is the "major" radius of the torus, the distance from the hole of
the donut to the middle of the ring of the donut, and r1 is the "minor"
radius of the torus, the distance from the middle of the ring of the donut to
the outer surface. The following object declaration is for a torus having
major radius 6.3 minor radius 3.5 (Making the maximum width just under 20).
//Torus having major radius sqrt(40), minor radius sqrt(12)
quartic {
< 1, 0, 0, 0, 2, 0, 0, 2, 0,
-104, 0, 0, 0, 0, 0, 0, 0, 0,
0, 0, 1, 0, 0, 2, 0, 56, 0,
0, 0, 0, 1, 0, -104, 0, 784 >
sturm
bounded_by { // bounded_by speeds up the render,
// see bounded_by
// explanation later
// in docs for more info.
sphere { <0, 0, 0>, 10 }
}
}
Poly, cubic and quartics are just like quadrics in that you don't have to
understand what one is to use one. The file SHAPESQ.INC has plenty of
pre-defined quartics for you to play with. The syntax for using a pre-defined
quartic is:
object { Quartic_Name }
As with the other shapes, these shapes can be translated, rotated, and
scaled. Because they are (almost always) infinite they do not respond to
automatic bounding. They can be used freely in CSG because they have a clear
defined "inside".
Polys use highly complex computations and will not always render perfectly.
If the surface is not smooth, has dropouts, or extra random pixels, try using
the optional keyword "sturm" in the definition. This will cause a slower, but
more accurate calculation method to be used. Usually, but not always, this
will solve the problem. If sturm doesn't work, try rotating, or translating
the shape by some small amount. See the sub-directory MATH for examples of
polys in scenes.
There are really so many different quartic shapes, we can't even begin to
list or describe them all. If you are interested and mathematically inclined,
an excellent reference book for curves and surfaces where you'll find more
quartic shape formulas is:
"The CRC Handbook of Mathematical Curves and Surfaces"
David von Seggern
CRC Press
1990
3.5.3.3 Quadric
A quadric surface (paraboloid). Quadric surfaces can produce shapes like
ellipsoids, spheres, cones, cylinders, paraboloids (dish shapes), and
hyperboloids (saddle or hourglass shapes). NOTE: Do not confuse "quaDRic"
with "quaRTic". A quadric is a 2nd order polynomial while a quartic is 4th
order. Quadrics render much faster and are less error-prone.
A quadric is defined in POV-Ray by:
quadric { <A,B,C>, <D,E,F>, <G,H,I>, J }
where A through J are float expressions.
This defines a surface of x,y,z points which satisfy the equation:
A x^2 + B y^2 + C z^2 +
D xy + E xz + F yz +
G x + H y + I z + J = 0
Different values of A,B,C,...J will give different shapes. So, if you take
any three dimensional point and use its x, y, and z coordinates in the above
equation, the answer will be 0 if the point is on the surface of the object.
The answer will be negative if the point is inside the object and positive if
the point is outside the object. Here are some examples:
X^2 + Y^2 + Z^2 - 1 = 0 Sphere
X^2 + Y^2 - 1 = 0 Infinite cylinder along the Z axis
X^2 + Y^2 - Z^2 = 0 Infinite cone along the Z axis
The easiest way to use these shapes is to include the standard file
"SHAPES.INC" into your program. It contains several pre-defined quadrics and
you can transform these pre-defined shapes (using translate, rotate, and
scale) into the ones you want.
You can invoke them by using the syntax,
object { Quadric_Name }
The pre-defined quadrics are centered about the origin <0, 0, 0> and have a
radius of 1. Don't confuse radius with width. The radius is half the diameter
or width making the standard quadrics 2 units wide.
Some of the pre-defined quadrics are,
Ellipsoid
Cylinder_X, Cylinder_Y, Cylinder_Z
QCone_X, QCone_Y, QCone_Z
Paraboloid_X, Paraboloid_Y, Paraboloid_Z
3.5.4 Constructive Solid Geometry
POV-Ray supports Constructive Solid Geometry (CSG) with four different
operations: difference, intersection, merge and union.
3.5.4.1 About CSG
Constructive Solid Geometry is a technique for combining two or more objects
to create a new object. It only works with solid objects, i.e. objects that
have a well-defined interior. This is the case for all objects described in
the sections "Finite Solid Primitives" and "Infinite Solid Primitives" .
CSG is based on the three boolean operations and, or and negate.
CSG shapes may be used in CSG shapes. In fact, CSG shapes may be used
anyplace that a standard shape is used.
The order of the component shapes with the CSG doesn't matter except in a
difference shape. For CSG differences, the first shape is visible and the
remaining shapes are cut out of the first.
Constructive solid geometry shapes may be translated, rotated, or scaled in
the same way as any shape. The shapes making up the CSG shape may be
individually translated, rotated, and scaled as well.
When using CSG, it is often useful to invert a shape so that it's inside-out.
The appearance of the shape is not changed, just the way that POV-Ray
perceives it. The inverse keyword can be used to do this for any shape.
When inverse is used, the "inside" of the shape is flipped to become the
"outside". For planes, "inside" is defined to be "in the opposite direction
to the "normal" or "up" direction.
Note that performing an intersection between a shape and some other inverse
shapes is the same as performing a difference. In fact, the difference is
actually implemented in this way in the code.
3.5.4.2 Inside and Outside
Most shape primitives, like spheres, boxes, and blobs, divide the world into
two regions. One region is inside the surface and one is outside.
Given any point in space, you can say it's either inside or outside any
particular primitive object (well, it could be exactly on the surface, but
numerical inaccuracies will put it to one side or the other).
Even planes have an inside and an outside. By definition, the surface normal
of the plane points towards the outside of the plane. (For a simple floor,
for example, the space above the floor is "outside" and the space below the
floor is "inside". For simple floors this in un-important, but for planes as
parts of CSG's it becomes much more important). CSG uses the concepts of
inside and outside to combine shapes together. Take the following situation:
Note: The diagrams shown here demonstrate the concepts in 2D and are intended
only as an analogy to the 3D case.
Note that the triangles and triangle-based shapes cannot be used as solid
objects in CSG since they have no clear inside and outside.
In this diagram, point 1 is inside object A only. Point 2 is inside B only.
Point 3 is inside both A and B while point 0 is outside everything.
3.5.4.3 Union
* = Object A
% = Object B
* 0
* * %
* * % %
* *% %
* 1 %* %
* % * 2 %
* % 3 * %
*******%******* %
% %
%%%%%%%%%%%%%%%%%
The union of a box and a cylinder.
Unions are simply "glue", used to bind two or more shapes into a single
entity that can be manipulated as a single object. The image above shows the
union of A and B. The new object created by the union operation can then be
scaled, translated, and rotated as a single shape. The entire union can share
a single texture, but each object contained in the union may also have its
own texture, which will override any matching texture statements in the
parent object.
union {
box { <-1.5, -1, -1>, <0.5, 1, 1> pigment { Red } }
cylinder { <0.5, 0, -1>, <0.5, 0, 1>, 1 pigment { Green } }
}
This union will contain three spheres. The first sphere is explicitly colored
Red while the other two will be shiny blue. Note that the shiny finish does
NOT apply to the first sphere. This is because the "pigment {Red}" is
actually shorthand for "texture {pigment {Red}}". It attaches an entire
texture with default normals and finish. The textures or pieces of textures
attached to the union apply ONLY to components with no textures. These
texturing rules also apply to intersection, difference and merge as well.
Earlier versions of POV-Ray placed restrictions on unions so you often had to
combine objects with composite statements. Those earlier restrictions have
been lifted so composite is no longer needed. Composite is still supported
for backwards compatibility but it is recommended that union now be used in
it's place since future support for the composite keyword is not guaranteed.
3.5.4.4 Intersection
A point is inside the intersection if it's inside both A AND B. This "logical
AND's" the shapes and gets the common part, most useful for "cutting"
infinite shapes off. The diagram below consists of only those parts common to
A and B.
%*
% *
% 3 *
%*******
The intersection between a box and a cylinder.
For example:
intersection {
box { <-1.5, -1, -1>, <0.5, 1, 1> pigment { Red } }
cylinder { <0.5, 0, -1>, <0.5, 0, 1>, 1 pigment { Green } }
}
3.5.4.5 Difference
A point is inside the difference if it's inside A but not inside B. The
results is a "subtraction" of the 2nd shape from the first shape.
*
* *
* *
* *
* 1 %
* %
* %
*******%
A cylinder is subtracted from a box..
For example:
difference {
box { <-1.5, -1, -1>, <0.5, 1, 1> pigment { Red } }
cylinder { <0.5, 0, -1>, <0.5, 0, 1>, 1 pigment { Green } }
}
3.5.4.6 Merge
As can be seen in the image for union, the inner surfaces where the objects
overlap are still present. On transparent or clipped objects these inner
surfaces cause problems. A merge object works just like union but it
eliminates the inner surfaces like shown in the figure.
*
* * %
* * % %
* *% %
* % %
* % %
* % %
*******% %
% %
%%%%%%%%%%%%%%%%%
Transparent union showing inner surfaces.
*
* * %
* * % %
* *% %
* %
* %
* %
*******% %
% %
%%%%%%%%%%%%%%%%%
Transparent merge without inner surfaces.
3.5.5 Light Sources
The last object we'll cover is the light source. Light sources have no
visible shape of their own. They are just points or areas which emit light.
Their full syntax is:
light_source {
<CENTER>
color <COLOUR>
[ spotlight ]
[ point_at <POINT> ]
[ radius RADIUS ]
[ falloff FALLOFF ]
[ tightness TIGHTNESS ]
[ area_light <AXIS1>, <AXIS2>, SIZE1, SIZE2 ]
[ adaptive ADAPTIVE ]
[ jitter JITTER ]
[ looks_like { OBJECT } ]
[ fade_distance FADE_DISTANCE ]
[ fade_power FADE_POWER ]
[ atmospheric_attenuation BOOL ]
}
The different type of light sources and the optional modifiers are described
in the following sections.
3.5.5.1 Point Lights
A point light source sends light of the specified color uniformly in all
directions. Its location is described by the CENTER vector and its color is
given by COLOR. It's syntax is:
light_source {
<CENTER>
color <COLOUR>
[ looks_like { OBJECT } ]
[ fade_distance FADE_DISTANCE ]
[ fade_power FADE_POWER ]
[ atmospheric_attenuation BOOL ]
}
3.5.5.2 Spotlights
A spotlight is a point light source where the rays of light are constrained
by a cone. The light is bright in the center of the spotlight and falls
off/darkens to soft shadows at the edges of the circle.
The syntax is:
light_source {
<CENTER>
color <COLOUR>
spotlight
point_at <POINT>
radius RADIUS
falloff FALLOFF
tightness TIGHTNESS
[ looks_like { OBJECT } ]
[ fade_distance FADE_DISTANCE ]
[ fade_power FADE_POWER ]
[ atmospheric_attenuation BOOL ]
}
The spotlight is identified by the "spotlight" keyword. Its located at CENTER
and points at POINT. The following illustrations will be helpful in
understanding how these values relate to each other:
(+) Spotlight <center>
/ \
/ \
/ \
/ \
/ \
/ \
+-----*-----+
^ point_at <point>
Spotlight center and point_at.
Spotlights also have three other parameters: radius, falloff, and tightness.
Think of a spotlight as two nested cones. The inner cone is specified by the
radius parameter, and is fully lit. The outer cone is the falloff cone beyond
which there is no light. The values for these two parameters are half the
opening angles of the corresponding cones.
The tightness value specifies how quickly the light dims, or falls off, in
the region between the radius (full brightness inside) cone and the falloff
(full darkness outside) cone. The default value for tightness is 10. Lower
tightness values will make the spot have very soft edges. High values will
make the edges sharper, the spot "tighter". Values from 1 to 100 are
acceptable.
Spotlights may be used anyplace that a normal light source is used. Like
normal light sources, they are invisible points. They are treated as shapes
and may be included in CSG shapes. They may also be used in conjunction with
area lights.
3.5.5.3 Cylindrical Lights
Cylindrical light sources work pretty much like spotlights except that the
light rays are constraint by a cylinder and not a cone. Their syntax is:
light_source {
<CENTER>
color <COLOUR>
cylinder
point_at <POINT>
radius RADIUS
falloff FALLOFF
tightness TIGHTNESS
[ looks_like { OBJECT } ]
[ fade_distance FADE_DISTANCE ]
[ fade_power FADE_POWER ]
[ atmospheric_attenuation BOOL ]
}
The radius, falloff and tightness keywords control the same features as with
the spotlight.
You should keep in mind that the cylindrical light source is still a point
light source. The rays emit from one point and are only constraint by a
cylinder. The light rays are not parallel.
3.5.5.4 Area Lights
Area light sources occupy a finite area of space. They can cast soft shadows
because they can partially block light.
The area lights used in POV-Ray are rectangular in shape, sort of like a flat
panel light. Rather than performing the complex calculations that would be
required to model a true area light, it is approximated as an array of
"point" light sources spread out over the area occupied by the light. The
intensity of each individual point light in the array is dimmed so that the
total amount of light emitted by the light is equal to the light color
specified in the declaration. It's syntax is:
light_source {
<CENTER>
color <COLOUR>
area_light <AXIS1>, <AXIS2>, SIZE1, SIZE2
adaptive ADAPTIVE
jitter JITTER
[ spotlight ]
[ point_at <POINT> ]
[ radius RADIUS ]
[ falloff FALLOFF ]
[ tightness TIGHTNESS ]
[ looks_like { OBJECT } ]
[ fade_distance FADE_DISTANCE ]
[ fade_power FADE_POWER ]
[ atmospheric_attenuation BOOL ]
}
The light's location and color are specified in the same way as a regular
light source.
The area_light command defines the size and orientation of the area light as
well as the number of lights in the light source array. The vectors AXIS1 and
AXIS2 specify the lengths and directions of the edges of the light. Since the
area lights are rectangular in shape these vectors should be perpendicular to
each other. The larger the size of the light the thicker that the soft part
of the shadow will be. The numbers SIZE1 and SIZE2 specify the dimensions of
the array of point lights. The larger the number of lights you use the
smoother your shadows will be but the longer they will take to render.
The adaptive command is used to enable adaptive sampling of the light source.
By default POV-Ray calculates the amount of light that reaches a surface from
an area light by shooting a test ray at every point light within the array.
As you can imagine this is very slow. Adaptive sampling on the other hand
attempts to approximate the same calculation by using a minimum number of
test rays. The number specified after the keyword controls how much adaptive
sampling is used. The higher the number the more accurate your shadows will
be but the longer they will take to render. If you're not sure what value to
use a good starting point is 'adaptive 1'. The adaptive command only accepts
integer values and cannot be set lower than 0. Adaptive sampling is explained
in more detail later.
The jitter command is optional. When used it causes the positions of the
point lights in the array to be randomly jittered to eliminate any shadow
banding that may occur. The jittering is completely random from render to
render and should not be used when generating animations.
Note: It's possible to specify spotlight parameters along with area_light
parameters to create "area spotlights." Using area spotlights is a good way
to speed up scenes that use area lights since you can confine the lengthy
soft shadow calculations to only the parts of your scene that need them.
An interesting effect that can be created using area lights as a linear
light. Rather than having a rectangular shape, a linear light stretches along
a line sort of like a thin fluorescent tube. To create a linear light just
create an area light with one of the array dimensions set to 1.
When performing adaptive sampling POV-Ray starts by shooting a test ray at
each of the four corners of the area light. If the amount of light received
from all four corners is approximately the same then the area light is
assumed to be either fully in view or fully blocked. The light intensity is
then calculated as the average intensity of the light received from the four
corners. However, if the light intensity from the four corners differs
significantly then the area light is partially blocked. The light is the
split into four quarters and each section is sampled as described above. This
allows POV-Ray to rapidly approximate how much of the area light is in view
without having to shoot a test ray at every light in the array.
While the adaptive sampling method is fast (relatively speaking) it can
sometimes produces inaccurate shadows. The solution is to reduce the amount
of adaptive sampling without completely turning it off. The number after the
adaptive keyword adjusts the number of times that the area light will be
split before the adaptive phase begins. For example if you use "adaptive 0" a
minimum of 4 rays will be shot at the light. If you use "adaptive 1" a
minimum of 9 rays will be shot (adaptive 2 = 25 rays, adaptive 3 = 81 rays,
etc).
Visually the pattern goes like this:
adaptive 0 1 2 3
rays 4 9 25 81
* . . . * * . * . * * * * * *
. . . . . . . . . . * * * * *
. . . . . * . * . * * * * * * etc...
. . . . . . . . . . * * * * *
* . . . * * . * . * * * * * *
Area light adaptive samples.
Obviously the more shadow rays you shoot the slower the rendering will be so
you should use the lowest value that gives acceptable results.
The number of rays never exceeds the values you specify for rows and columns
of points. For example: area_light x,y,4,4 specifies a 4 by 4 array of
lights. If you specify adaptive 3 it would mean that you should start with a
9 by 9 array. In this case no adaptive sampling is done. The 4 by 4 array is
used.
3.5.5.5 Shadowless
Using the "shadowless" keyword you can stop a light source from casting
shadows.
3.5.5.6 Looks_like
Normally the light source itself has no visible shape. The light simply
radiates from an invisible point or area. You may give a light source a any
shape by adding a "looks_like {OBJECT }" statement.
There is an implied "no_shadow" attached to the looks_like object so that
light is not blocked by the object. Without the automatic no_shadow, the
light inside the object would not escape. The object would, in effect, cast a
shadow over everything.
If you want the attached object to block light then you should attach it with
a union and not a looks_like as follows:
union {
light_source {<100,200,-300> color White}
object {My_Lamp_Shade}
}
3.5.5.7 Light Fading
By default POV-Ray does not diminish light from any light source as it
travels through space. In order to get a more realistic effect
"fade_distance" and "fade_power" can be used to model the distance based
falloff in light intensity.
The "fade_distance" keyword is used to specify the distance at which the full
light intensity arrives, i.e. the intensity which was given by the "color"
keyword. The actual attenuation is described by the "fade_power" keyword,
which determines the falloff rate. E.g. Linear or quadratic falloff can be
used by setting FADE_POWER to 1 or 2 respectively. The complete formula to
calculate the factor by which the light is attenuated is:
2
attenuation = --------------------------------------,
1 + (d / FADE_DISTANCE) ^ FADE_POWER
with d being the distance the light has traveled.
You should note two important facts: First, for FADE_DISTANCEs larger than 1
the light intensity at distances smaller than FADE_DISTANCE actually
increases. This is necessary to get the light source color at distance
FADE_DISTANCE. Second, only light coming directly from light sources is
attenuated. Reflected or refracted light is not attenuated by distance.
3.5.5.8 Atmospheric Attenuation
Normally light coming from light sources is not influenced by fog or
atmosphere. This behavior can be changed by turning the atmospheric
attenuation for a given light source on. All light coming from this light
source will now be diminished as it travels through fog or atmosphere. This
results in an distance-based, exponential intensity falloff ruled by the used
fog or atmosphere. If there is no fog or atmosphere no change will be seen.
3.5.6 Object Modifiers
A variety of modifiers may be attached to objects. Transformations such as
translate, rotate and scale have already been discussed. Textures are in a
section of their own below. Here are three other important modifiers:
clipped_by, bounded_by and no_shadow. Although the examples below use object
statements and object identifiers, these modifiers may be used on any type of
object such as sphere, box etc.
3.5.6.1 Clipped_By
The "clipped_by" statement is technically an object modifier but it provides
a type of CSG similar to CSG intersection. You attach a clipping object like
this:
object {
My_Thing
clipped_by{plane{y,0}}
}
Every part of the object "My_Thing" that is inside the plane is retained
while the remaining part is clipped off and discarded. In an intersection
object, the hole is closed off. With clipped_by it leaves an opening. For
example this diagram shows our object "A" being clipped_by a plane {y,0}.
* *
* *
* *
***************
A cylinder clipped by a box.
Clipped_by may be used to slice off portions of any shape. In many cases it
will also result in faster rendering times than other methods of altering a
shape.
Often you will want to use the clipped_by and bounded_by options with the
same object. The following shortcut saves typing and uses less memory.
object {
My_Thing
bounded_by{box{<0,0,0>,<1,1,1>}}
clipped_by{bounded_by}
}
3.5.6.2 Bounded_By
The calculations necessary to test if a ray hits an object can be quite time
consuming. Each ray has to be tested against every object in the scene.
POV-Ray attempts so speed up the process by building a set of invisible
boxes, called bounding boxes, which cluster the objects together. This way a
ray that travels in one part of the scene doesn't have to be tested against
objects in another far away part of the scene. When large number objects are
present the boxes are nested inside each other. POV-Ray can use bounding
boxes on any finite object and even some clipped or bounded quadrics. However
infinite objects (such as a planes, quartic, cubic and poly) cannot be
automatically bound. CSG objects are automatically bound if they contain
finite (and in some cases even infinite) objects. This works by applying the
CSG set operations to the bounding boxes of all objects used inside the CSG
object. For difference and intersection operations this will hardly ever lead
to an optimal bounding box. It's sometimes better (depending on the
complexity of the CSG object) to use a bounded_by statement with such shapes.
Normally bounding shapes are not necessary but there are cases where they can
be used to speed up the rendering of complex objects. Bounding shapes tell
the ray tracer that the object is totally enclosed by a simple shape. When
tracing rays, the ray is first tested against the simple bounding shape. If
it strikes the bounding shape, then the ray is further tested against the
more complicated object inside. Otherwise the entire complex shape is
skipped, which greatly speeds rendering.
To use bounding shapes, simply include the following lines in the declaration
of your object:
bounded_by {
object { ... }
}
An example of a Bounding Shape:
intersection {
sphere {<0,0,0>, 2}
plane {<0,1,0>, 0}
plane {<1,0,0>, 0}
bounded_by {sphere {<0,0,0>, 2}}
}
The best bounding shape is a sphere or a box since these shapes are highly
optimized, although, any shape may be used. If the bounding shape is itself a
finite shape which responds to bounding slabs then the object which it
encloses will also be used in the slab system.
CSG shapes can benefit from bounding slabs without a bounded_by statement
however they may do so inefficiently in intersection, difference and merge.
In these three CSG types the automatic bound used covers all of the component
objects in their entirety. However the result of these intersections may
result in a smaller object. Compare the sizes of the illustrations for union
and intersection in the CSG section above. It is possible to draw a much
smaller box around the intersection of A and B than the union of A and B yet
the automatic bounds are the size of union {A B} regardless of the kind of
CSG specified.
While it is almost always a good idea to manually add a bounded_by to
intersection, difference and merge, it is often best to NOT bound a union. If
a union has no bounded_by and no clipped_by then POV-Ray can internally split
apart the components of a union and apply automatic bounding slabs to any of
its finite parts. Note that some utilities such as RAW2POV may be able to
generate bounds more efficiently than POV-Ray's current system. However most
unions you create yourself can be easily bounded by the automatic system. For
technical reasons POV-Ray cannot split a merge object. It is probably best to
hand bound a merge, especially if it is very complex.
Note that if bounding shape is too small or positioned incorrectly, it may
clip the object in undefined ways or the object may not appear at all. To do
true clipping, use clipped_by as explained above. Often you will want to use
the clipped_by and bounded_by options with the same object. The following
shortcut saves typing and uses less memory.
object {
My_Thing
clipped_by{box{<0,0,0>,<1,1,1>}}
bounded_by{clipped_by}
}
3.5.6.3 Hollow
POV-Ray by default assumes that objects are made of a solid material that
completely fills the interior of an object. By adding the "hollow" keyword to
the object you can make it hollow.
The "hollow" keyword is very useful if you want atmospheric effects to exist
inside an object. It is even required for objects containing a halo.
3.5.6.4 No_Shadow
You may specify the no_shadow keyword in an object and that object will not
cast a shadow. This is useful for special effects and for creating the
illusion that a light source actually is visible. This keyword was necessary
in earlier versions of POV-Ray which did not have the "looks_like" statement.
Now it is useful for creating things like laser beams or other unreal
effects.
Simply attach the keyword as follows:
object {
My_Thing
no_shadow
}
3.6 Textures
The texture describes what the object looks like, i.e. its material. Textures
are combinations of pigments, normals, finishes, and halos. Pigment is the
color or pattern of colors inherent in the material. Normal is a method of
simulating various patterns of bumps, dents, ripples or waves by modifying
the surface normal vector. Finish describes the reflective and refractive
properties of a material. Halo simulates effects like clouds, fog, fire etc.
by using a density field defined inside the object.
A plain texture consists of a single pigment, an optional normal, a single
finish and optionally one or more halos. A special texture combines two or
more textures using a pattern or blending function. Special textures may be
made quite complex by nesting patterns within patterns. At the innermost
levels however, they are made up from plain textures. Note that allthough we
call a plain texture "plain" it may be a very complex texture. The term
"plain" only means that it has a single pigment, normal, finish and halo.
The most complete form for defining a plain texture is as follows:
texture {
TEXTURE_IDENTIFIER
pigment {...}
normal {...}
finish {...}
halo {...}
TRANSFORMATIONS
}
Each of the items in a texture are optional but if they are present, the
identifier must be first and the transformations must be last. The pigment,
normal, and finish parameters modify any pigment, normal and finish already
specified in the TEXTURE_IDENTIFIER. Any halos are added to the already
existing halos. If no texture identifier is specified then the pigment,
normal and finish statements modify the current default values and any halo
is added to the default halo, if any. TRANSFORMATIONs are translate, rotate,
scale and matrix statements. They should be specified last.
The sections below describe all of the options available in pigments,
normals, finishes and halos. Special textures are covered later.
3.6.1 Pigment
The color or pattern of colors for an object is defined by a pigment
statement. All plain textures must have a pigment. If you do not specify one,
the default pigment is used. A pigment statement is part of a texture
specification. However it can be tedious to type "texture {pigment {...}}"
just to add a color to an object. Therefore you may attach a pigment directly
to an object without explicitly specifying that it as part of a texture. For
example:
//this... //can be shortened to this...
object { object {
My_Object My_Object
texture { pigment {color Red}
pigment {color Red} }
}
}
The color you define is the way you want the object to look if fully
illuminated. You pick the basic color inherent in the object and POV-Ray
brightens or darkens it depending on the lighting in the scene. The parameter
is called "pigment" because we are defining the basic color the object
actually is rather than how it looks.
The most complete form for defining a pigment is as follows:
pigment {
PIGMENT_IDENTIFIER
PATTERN_TYPE
PIGMENT_MODIFIERS...
}
Each of the items in a pigment are optional but if they are present, they
should be in the order shown above to insure that the results are as
expected. Any items after the PIGMENT_IDENTIFIER modify or override settings
given in the identifier. If no identifier is specified then the items modify
the pigment values in the current default texture. Valid PIGMENT_MODIFIERS
are color_map, pigment_map, image_map and quick_color statements as well as
any of the generic PATTERN_MODIFIERS such as translate, rotate, scale,
turbulence, wave shape and warp statements. Such modifiers apply only to the
pigment and not to other parts of the texture. Modifiers should be specified
last.
The various PATTERN_TYPEs fall into roughly 4 categories. Each category is
discussed below. They are solid color, color list patterns, color mapped
patterns and image maps.
3.6.1.1 Solid Color Pigments
The simplest type of pigment is a solid color. To specify a solid color you
simply put a color specification inside a pigment. For example:
pigment {color Orange}
A color specification consists of the option keyword color followed by a
color identifier or by a specification of the amount of red, green, blue,
filtered and unfiltered transparency in the surface. See section "Specifying
Colors" for more details about colors. Any pattern modifiers used with a
solid color are ignored because there is no pattern to modify.
3.6.1.2 Color List Pigments
There are three color list patterns: checker, hexagon and brick. The result
is a pattern of solid colors with distinct edges rather than a blending of
colors as with color mapped patterns. Each of these patterns is covered in
more detail in a later section. The syntax for each is:
pigment { brick COLOR1, COLOR2 MODIFIERS ... }
pigment { checker COLOR1, COLOR2 MODIFIERS ... }
pigment { hexagon COLOR1, COLOR2, COLOR3 MODIFIERS ... }
Each COLORn is any valid color specification. There should be a comma between
each color or the color keyword should be used as a separator so that POV-Ray
can determine where each color specification starts and ends.
3.6.1.3 Color Maps
Most of the color patterns do not use abrupt color changes of just two or
three colors like those in the brick, checker or hexagon patterns. They
instead use smooth transitions of many colors that gradually change from one
point to the next. The colors are defined in a pigment modifier called a
color map that describes how the pattern blends from one color to the next.
Each of the various pattern types available is in fact a mathematical
function that takes any x,y,z location and turns it into a number between 0.0
and 1.0 inclusive. That number is used to specify what mix of colors to use
from the color map.
A color map is specified by...
pigment{
PATTERN_TYPE
color_map {
[ NUM_1 COLOR_1]
[ NUM_2 COLOR_2]
[ NUM_3 COLOR_3]
...
}
PIGMENT_MODIFIERS...
}
Where NUM_1, NUM_2... are float values between 0.0 and 1.0 inclusive.
COLOR_1, COLOR_2... are color specifications. NOTE: the [] brackets are part
of the actual statement. They are not notational symbols denoting optional
parts. The brackets surround each entry in the color map. There may be from 2
to 256 entries in the map. The alternate spelling colour_map may be used.
For example,
sphere {
<0,1,2>, 2
pigment {
gradient x //this is the PATTERN_TYPE
color_map {
[0.1 color Red]
[0.3 color Yellow]
[0.6 color Blue]
[0.6 color Green]
[0.8 color Cyan]
}
}
}
The pattern function is evaluated and the result is a value from 0.0 to 1.0.
If the value is less than the first entry (in this case 0.1) then the first
color (Red) is used. Values from 0.1 to 0.3 use a blend of red and yellow
using linear interpolation of the two colors. Similarly values from 0.3 to
0.6 blend from yellow to blue. Note that the 3rd and 4th entries both have
values of 0.6. This causes an immediate abrupt shift of color from blue to
green. Specifically a value that is less than 0.6 will be blue but exactly
equal to 0.6 will be green. Moving along, values from 0.6 to 0.8 will be a
blend of green and cyan. Finally any value greater than or equal to 0.8 will
be cyan.
If you want areas of unchanging color you simply specify the same color for
two adjacent entries. For example:
color_map {
[0.1 color Red]
[0.3 color Yellow]
[0.6 color Yellow]
[0.8 color Green]
}
In this case any value from 0.3 to 0.6 will be pure yellow.
A color_map may be used with any pattern except brick, checker, hexagon and
image_map.
You may declare and use color_map identifiers. For example:
#declare Rainbow_Colors=
color_map {
[0.0 color Magenta]
[0.33 color Yellow]
[0.67 color Cyan]
[1.0 color Magenta]
}
object{My_Object
pigment{
gradient x
color_map{Rainbow_Colors}
}
}
3.6.1.4 Pigment Maps
In addition to specifying blended color with a color_map, you may create a
blend of pigments using a pigment_map. The syntax for a pigment_map is
identical color_map except you specify a pigment in each map entry.
A pigment_map is specified by...
pigment{
PATTERN_TYPE
pigment_map {
[ NUM_1 PIGMENT_BODY_1]
[ NUM_2 PIGMENT_BODY_2]
[ NUM_3 PIGMENT_BODY_3]
...
}
PIGMENT_MODIFIERS...
}
Where NUM_1, NUM_2... are float values between 0.0 and 1.0 inclusive. A
PIGMENT_BODY is anything that would normally appear inside a pigment {...}
statement but the pigment keyword and {} braces are not needed. NOTE: the []
brackets are part of the actual statement. They are not notational symbols
denoting optional parts. The brackets surround each entry in the map. There
may be from 2 to 256 entries in the map.
For example,
sphere {
<0,1,2>, 2
pigment {
gradient x //this is the PATTERN_TYPE
pigment_map {
[0.3 wood scale 0.2]
[0.3 Jade] //this is a pigment identifier
[0.6 Jade]
[0.9 marble turbulence 1]
}
}
}
When the gradient x function returns values from 0.0 to 0.3 the scaled wood
pigment is used. From 0.3 to 0.6 the pigment identifier Jade is used. From
0.6 up to 0.9 a blend of Jade and a turbulent marble is used. From 0.9 on up
only the turbulent marble is used.
Pigment maps may be nested to any level of complexity you desire. The
pigments in a map may have color_map or pigment_maps or any type of pigment
you want. Any entry of a pigment_map may be a solid color however if all
entries are solid colors you should use a color_map which will render
slightly faster.
Entire pigments may also be used with the block patterns such as checker,
hexagon and brick. For example...
pigment {
checker
pigment { Jade scale .8 }
pigment { White_Marble scale .5 }
}
Note that in the case of block patterns, the pigment {...} wrapping is
required around the pigment information.
A pigment_map is also used with the average pigment type. See "Average" for
details.
You may not use pigment_map or individual pigments with an image_map. See
"texture_map" for an alternative way to do this.
3.6.1.5 Image Maps
When all else fails and none of the above pigment pattern types meets your
needs, you can use an image map to wrap a 2-D bit-mapped image around your
3-D objects.
3.6.1.5.1 Specifying an Image Map
The syntax for image_map is...
pigment {
image_map {
FILE_TYPE "filename"
MODIFIERS...
}
}
Where FILE_TYPE is one of the following keywords gif, tga, iff, ppm, pgm,
png, or sys. This is followed by the name of the file in quotes. Several
optional modifiers may follow the file specification. The modifiers are
described below. Note: Earlier versions of POV-Ray allowed some modifiers
before the FILE_TYPE but that syntax is being phased out in favor of the
syntax described here.
Filenames specified in the image_map statements will be searched for in the
home (current) directory first, and if not found, will then be searched for
in directories specified by any "-L" (library path) options active. This
would facilitate keeping all your image maps files in a separate
subdirectory, and giving an "-L" option on the command line to where your
library of image maps are.
By default, the image is mapped onto the X-Y plane. The image is "projected"
onto the object as though there were a slide projector somewhere in the -Z
direction. The image exactly fills the square area from x,y coordinates (0,0)
to (1,1) regardless of the image's original size in pixels. If you would like
to change this default, you may translate, rotate or scale the pigment or
texture to map it onto the object's surface as desired.
In the section "Checker" we explained checker pigment patterns, we described
the checks as solid cubes of colored clay from which objects are carved. With
image maps you should imagine that each pixel is a long, thin, square,
colored rod that extends parallel to the Z axis. The image is made from rows
and columns of these rods bundled together and the object is then carved from
the bundle.
If you would like to change this default orientation, you may translate,
rotate or scale the pigment or texture to map it onto the object's surface as
desired.
3.6.1.5.2 The map_type Option
The default projection of the image onto the X-Y plane is called a "planar
map type". This option may be changed by adding the "map_type" keyword
followed by a number specifying the way to wrap the image around the object.
A "map_type 0" gives the default planar mapping already described.
A "map_type 1" is a spherical mapping. It assumes that the object is a sphere
of any size sitting at the origin. The Y axis is the north/south pole of the
spherical mapping. The top and bottom edges of the image just touch the pole
regardless of any scaling. The left edge of the image begins at the positive
X axis and wraps the image around the sphere from "west" to "east" in a -Y
rotation. The image covers the sphere exactly once. The "once" keyword has no
meaning for this type.
With "map_type 2" you get a cylindrical mapping. It assumes that a cylinder
of any diameter lies along the Y axis. The image wraps around the cylinder
just like the spherical map but the image remains 1 unit tall from y=0 to
y=1. This band of color is repeated at all heights unless the "once" keyword
is applied.
Finally "map_type 5" is a torus or donut shaped mapping. It assumes that a
torus of major radius 1 sits at the origin in the X-Z plane. The image is
wrapped around similar to spherical or cylindrical maps. However the top and
bottom edges of the map wrap over and under the torus where they meet each
other on the inner rim.
Types 3 and 4 are still under development.
Note: The "map_type" option may also be applied to bump_map and material_map
statements.
3.6.1.5.3 The Filter and Transmit Bitmap Modifiers
To make all or part of an image map transparent, you can specify filter
and/or transmit values for the color palette/registers of PNG, GIF or IFF
pictures (at least for the modes that use palettes). You can do this by
adding the keyword filter or transmit following the filename. The keyword is
followed by two numbers. The first number is the palette number value and the
second is the amount of transparency. The values should be separated by a
comma. For example:
image_map {
gif "mypic.gif"
filter 0, 0.5 // Make color 0 50% filtered transparent
filter 5, 1.0 // Make color 5 100% filtered transparent
transmit 8, 0.3 // Make color 8 30% non-filtered transparent
}
You can give the entire image a filter or transmit value using filter all
VALUE or transmit all VALUE .
For example:
image_map {
gif "stnglass.gif"
filter all 0.9
}
Note: Early versions of POV-Ray used the keyword alpha to specify filtered
transparency however that word is often used to descrbe non-filtered
transparency. For this reason, alpha is no longer used.
See "filter" and "transmit" for details on the differences between filtered
and non-filtered transparency.
3.6.1.5.4 Using the Alpha Channel
Another way to specify non-filtered transmit transparency in an image map is
by using the alpha channel .
PNG allows you to store a different transparency for each color index in the
PNG file, if desired. If your paint programs support this feature of PNG, you
can do the transparency editing within your paint program rather than
specifying transmit values for each color in the POV file. Since PNG and TGA
image formats can also store full alpha channel (transparency) information,
you can generate image maps that have transparency which isn't dependent on
the color of a pixel, but rather its location in the image.
Although POV uses transmit 0.0 to specify no transparency and 1.0 to specify
full transparency, the alpha data ranges from 0 to 255 in the opposite
direction. Alpha data 0 means the same as transmit 1.0 and alpha data 255
produces transmit 0.0.
3.6.1.6 Quick Color
When developing POV-Ray scenes its often useful to do low quality test runs
that render faster. The +Q command line switch can be used to turn off some
time consuming color pattern and lighting calculations to speed things up.
However all settings of +Q5 or lower turns off pigment calculations and
creates gray objects.
By adding a "quick_color" to a pigment you tell POV-Ray what solid color to
use for quick renders instead of a patterned pigment. For example:
pigment {
gradient x
color_map{
[0.0 color Yellow]
[0.3 color Cyan]
[0.6 color Magenta]
[1.0 color Cyan]
}
turbulence 0.5
lambda 1.5
omega 0.75
octaves 8
quick_color Neon_Pink
}
This tells POV-Ray to use solid Neon_Pink for test runs at quality +Q5 or
lower but to use the turbulent gradient pattern for rendering at +Q6 and
higher.
Note that solid color pigments such as
pigment {color Magenta}
automatically set the quick_color to that value. You may override this if you
want. Suppose you have 10 spheres on the screen and all are Yellow. If you
want to identify them individually you could give each a different
quick_color like this:
sphere { <1,2,3>,4
pigment { color Yellow quick_color Red }
}
sphere { <-1,-2,-3>,4
pigment { color Yellow quick_color Blue }
}
and so on. At +Q6 or higher they will all be Yellow but at +Q5 or lower each
would be different colors so you could identify them.
3.6.2 Normal
Ray tracing is known for the dramatic way it depicts reflection, refraction
and lighting effects. Much of our perception depends on the reflective
properties of an object. Ray tracing can exploit this by playing tricks on
our perception to make us see complex details that aren't really there.
Suppose you wanted a very bumpy surface on the object. It would be very
difficult to mathematically model lots of bumps. We can however simulate the
way bumps look by altering the way light reflects off of the surface.
Reflection calculations depend on a vector called a "surface normal" vector.
This is a vector which points away from the surface and is perpendicular to
it. By artificially modifying (or perturbing) this normal vector you can
simulate bumps.
The normal {...} statement is the part of a texture which defines the pattern
of normal perturbations to be applied to an object. Like the pigment
statement, you can omit the surrounding texture block to save typing. Do not
forget however that there is a texture implied. For example...
//this... //can be shortened to this...
object { object {
My_Object My_Object
texture { pigment {color Purple}
pigment {color Purple} normal {bumps 0.3}
normal {bumps 0.3} }
}
}
Note that attaching a normal pattern does not really modify the surface. It
only affects the way light reflects or refracts at the surface so that it
looks bumpy.
The most complete form for defining a normal is as follows:
normal {
NORMAL_IDENTIFIER
PATTERN_TYPE FloatValue
NORMAL_MODIFIERS
TRANSFORMATIONS...
}
Each of the items in a normal are optional but if they are present, they
should be in the order shown above to insure that the results are as
expected. Any items after the NORMAL_IDENTIFIER modify or override settings
given in the identifier. If no identifier is specified then the items modify
the normal values in the current default texture. The PATTERN_TYPE may
optionally be followed by a float value that controls the apparent depth of
the bumps. Typical values range from 0.0 to 1.0 but any value may be used.
Negative values invert the pattern. The default value if none is specified is
0.5.
Valid NORMAL_MODIFIERS are slope_map, normal_map, bump_map and bump_size
statements as well as any of the generic PATTERN_MODIFIERS such as translate,
rotate, scale, turbulence, wave shape and warp statements. Such modifiers
apply only to the normal and not to other parts of the texture. Modifiers
should be specified last.
There are 3 basic types of NORMAL_PATTERN_TYPEs. They are pattern normals,
specialized normals and bump_map. They differ in the types of modifiers you
may use with them. Originally POV-Ray had some patterns which were
exclusively used for pigments while others were exclusively used for normals.
New in POV-Ray 3.0 you can use any pattern for either pigments or normals.
For example it is now valid to use ripples as a pigment or wood as a normal
type. The patterns bumps, dents, ripples, waves, wrinkles and bump_map were
once exclusively normal patterns which could not be used as pigments. Because
these 6 types use specialized normal modification calculations, they cannot
have slope_map, normal_map or wave shape modifiers. All other normal pattern
types may use them.
3.6.2.1 Slope Maps
A slope_map is a normal pattern modifier which gives the user a great deal of
control over the exact shape of the bumpy features. It is best illustrated
with a gradient normal pattern. Suppose you have...
plane{z,0
pigment{White}
normal {gradient x}
}
this gives a ramp wave pattern that looks like small linear ramps that climb
from the points at x=0 to x=1 and then abruptly drops to 0 again to repeat
the ramp from x=1 to x=2. A slope_map turns this simple linear ramp into
almost any wave shape you want. The syntax is as follows...
normal{
PATTERN_TYPE Value
slope_map {
[ NUM_1 POINT_SLOPE_1]
[ NUM_2 POINT_SLOPE_2]
[ NUM_3 POINT_SLOPE_3]
...
}
NORMAL_MODIFIERS...
}
NOTE: the [] brackets are part of the actual statement. They are not
notational symbols denoting optional parts. The brackets surround each entry
in the slope map. There may be from 2 to 256 entries in the map.
The NUM_1, NUM_2... are float values between 0.0 and 1.0 inclusive.
POINT_SLOPE_1, POINT_SLOPE__2... are 2 component vectors such as <0,1> where
the first value represents the apparent height of the wave and the second
value represents the slope of the wave at that point. The height should range
between 0.0 and 1.0 but any value could be used.
The slope value is the change in height per unit of distance. For example a
slope of zero means flat, a slope of 1.0 means slope upwards at a 45 degree
angle, and a slope of -1 means slope down at 45 degrees. Theoretically a
slope straight up would have infinite slope. In practice, slope values should
be kept in the range -3.0 to +3.0. Keep in mind that this is only the
visually apparent slope. A normal does not actually change the surface.
For example here is how to make the ramp slope up for the first half and back
down on the second half creating a triangle wave with a sharp peak in the
center.
normal {
gradient x //this is the PATTERN_TYPE
slope_map {
[0 <0, 1>] // start at bottom and slope up
[0.5 <1, 1>] // halfway through reach top still climbing
[0.5 <1,-1>] // abruptly slope down
[1 <0,-1>] // finish on down slope at bottom
}
}
The pattern function is evaluated and the result is a value from 0.0 to 1.0.
The first entry says that at x=0, the apparent height is 0 and the slope is
1. At x=0.5 we are at height 1 and slope is still up at 1. The third entry
also specifies that at x=0.5 (actually at some tiny fraction above 0.5) we
have height 1 but slope -1 which is downwards. Finally at x=1 we are at
height 0 again and still sloping down with slope -1.
Although this example connects the points using straight lines, the shape is
actually a cubic spline. This example creates a smooth sine wave.
normal {
gradient x //this is the PATTERN_TYPE
slope_map {
[0 <0.5, 1>] // start in middle and slope up
[0.25 <1.0, 0>] // flat slope at top of wave
[0.5 <0.5,-1>] // slope down at mid point
[0.75 <0.0, 0>] // flat slope at bottom
[1 <0.5, 1>] // finish in middle and slope up
}
}
This example starts at height 0.5 sloping up at slope 1. At a fourth of the
way through we are at the top of the curve at height 1 with slope 0 which is
flat. The space between these two is a gentle curve because the start and end
slopes are different. At half way we are at half height sloping down to
bottom out at 3/4ths. By the end we are climbing at slope 1 again to complete
the cycle.
There are more examples in SLOPEMAP.POV in the sample scenes.
A slope_map may be used with any pattern except brick, checker, hexagon,
bumps, dents, ripples, waves, wrinkles and bump_map.
You may declare and use slope_map identifiers. For example:
#declare Fancy_Wave=
slope_map { // Now let's get fancy
[0.0 <0, 1>] // Do tiny triangle here
[0.2 <1, 1>] // down
[0.2 <1,-1>] // to
[0.4 <0,-1>] // here.
[0.4 <0, 0>] // Flat area
[0.5 <0, 0>] // through here.
[0.5 <1, 0>] // Square wave leading edge
[0.6 <1, 0>] // trailing edge
[0.6 <0, 0>] // Flat again
[0.7 <0, 0>] // through here.
[0.7 <0, 3>] // Start scallop
[0.8 <1, 0>] // flat on top
[0.9 <0,-3>] // finish here.
[0.9 <0, 0>] // Flat remaining through 1.0
}
object{My_Object
pigment{White}
normal{
wood
slope_map{Fancy_Wave}
}
}
3.6.2.2 Normal Maps
Most of the time you will apply single normal pattern to an entire surface
but you may also create a pattern or blend of normals using a normal_map. The
syntax for a normal_map is identical to pigment_map except you specify a
normal in each map entry.
A normal_map is specified by...
normal{
PATTERN_TYPE
normal_map {
[ NUM_1 NORMAL_BODY_1]
[ NUM_2 NORMAL_BODY_2]
[ NUM_3 NORMAL_BODY_3]
...
}
NORMAL_MODIFIERS...
}
Where NUM_1, NUM_2... are float values between 0.0 and 1.0 inclusive. A
NORMAL_BODY is anything that would normally appear inside a normal {...}
statement but the normal keyword and {} braces are not needed. NOTE: the []
brackets are part of the actual statement. They are not notational symbols
denoting optional parts. The brackets surround each entry in the map. There
may be from 2 to 256 entries in the map.
For example,
normal {
gradient x //this is the PATTERN_TYPE
normal_map {
[0.3 bumps scale 2]
[0.3 dents]
[0.6 dents]
[0.9 marble turbulence 1]
}
}
When the gradient x function returns values from 0.0 to 0.3 then the scaled
bumps normal is used. From 0.3 to 0.6 dents are From 0.6 up to 0.9 a blend of
dents and a turbulent marble is used. From 0.9 on up only the turbulent
marble is used.
Normal maps may be nested to any level of complexity you desire. The normals
in a map may have slope_map or normal_maps or any type of normal you want.
A normal_map is also used with the average normal type. See "Average" for
details.
Entire normals may also be used with the block patterns such as checker,
hexagon and brick. For example...
normal {
checker
normal{gradient x scale .2}
normal{gradient y scale .2}
}
}
Note that in the case of block patterns, the normal {...} wrapping is
required around the normal information.
You may not use normal_map or individual normals with a bump_map. See
"texture_map" for an alternative way to do this.
3.6.2.3 Bump Maps
When all else fails and none of the above normal pattern types meets your
needs, you can use a bump map to wrap a 2-D bit-mapped bump pattern around
your 3-D objects.
Instead of placing the color of the image on the shape like an image_map,
bump_map perturbs the surface normal based on the color of the image at that
point. The result looks like the image has been embossed into the surface. By
default, bump_map uses the brightness of the actual color of the pixel.
Colors are converted to gray scale internally before calculating height.
Black is a low spot, white is a high spot. The image's index values may be
used instead (see use_index) below.
3.6.2.3.1 Specifying a Bump Map
The syntax for bump_map is...
normal {
bump_map {
FILE_TYPE "filename"
BITMAP_MODIFIERS...
}
NORMAL_MODIFIERS...
}
Where FILE_TYPE is one of the following keywords gif, tga, iff, ppm, pgm,
png, or sys. This is followed by the name of the file using any valid string
expression. Several optional modifiers may follow the file specification. The
modifiers are described below. Note: Earlier versions of POV-Ray allowed some
modifiers before the FILE_TYPE but that syntax is being phased out in favor
of the syntax described here.
Filenames specified in the bump_map statements will be searched for in the
home (current) directory first, and if not found, will then be searched for
in directories specified by any +L switches or Library_Path= options. This
would facilitate keeping all your bump maps files in a separate subdirectory,
and specifying a library path to them. Note that any operating system default
paths are not searched unless you also specify them as a Library_Path.
By default, the bump pattern is mapped onto the X-Y plane. The bumps are
"projected" onto the object as though there were a slide projector somewhere
in the -Z direction. The bump pattern exactly fills the square area from x,y
coordinates (0,0) to (1,1) regardless of the bitmaps's original size in
pixels. If you would like to change this default, you may translate, rotate
or scale the normal or texture to map it onto the object's surface as
desired.
The file name is optionally followed by one or more BITMAP_MODIFIERS. The
bump_size, use_color and use_index modifiers are specific to bump maps and
are discussed in the following sections. See "bitmap modifiers" for other
general bitmap modifiers.
After a bump_map statement but still inside the normal statement you may
apply any legal normal modifiers except slope_map and pattern wave forms.
3.6.2.3.2 Bump_Size
The relative bump size can be scaled using bump_size modifier. The bump_size
number can be any number other than 0 but typical values are from about 0.1
to as high as 4.0 or 5.0.
normal {
bump_map {
gif "stuff.gif"
bump_size 5.0
}
}
Originally bump_size could only be used inside bump_map but it can now be
used with any normal. Typically it is used to override a previously defined
size. For example:
normal {
My_Normal //this is a previously defined normal identifier
bump_size 2.0
}
3.6.2.3.3 Use_Index and Use_Color
Usually the bump_map converts the color of the pixel in the map to a gray
scale intensity value in the range 0.0 to 1.0 and calculates the bumps based
on that value. If you specify use_index, the bump_map uses the color's
palette number to compute as the height of the bump at that point. So, color
#0 would be low and color #255 would be high. The actual color of the pixels
doesn't matter when using the index. This option is only available on palette
based formats. The use_color keyword may be specified to explicitly note that
the color methods should be used instead. The alternate spelling use_colour
is also valid. These modifiers may only be used inside the bump_map
statement.
3.6.3 Finish
The finish properties of a surface can greatly affect its appearance. How
does light reflect? What happens when light passes through? What kind of
highlights are visible. To answer these questions you need a finish
statement.
The "finish {...}" statement is the part of a texture which defines the
various finish properties to be applied to an object. Like the pigment or
normal statement, you can omit the surrounding texture block to save typing.
Do not forget however that there is a texture implied. For example...
this... can be shortened to this...
object { object {
My_Object My_Object
texture { pigment {color Purple}
pigment {color Purple} finish {phong 0.3}
finish {phong 0.3} }
}
}
The most complete form for defining a finish is as follows:
finish {
FINISH_IDENTIFIER
[ ambient COLOR ]
[ diffuse FLOAT ]
[ brilliance FLOAT ]
[ phong FLOAT ]
[ phong_size FLOAT ]
[ specular FLOAT ]
[ roughness FLOAT ]
[ metallic [ BOOL ] ]
[ reflection COLOR ]
[ refraction FLOAT ]
[ ior FLOAT ]
[ caustics FLOAT ]
[ fade_distance FLOAT ]
[ fade_power FLOAT ]
[ irid { thickness FLOAT turbulence VECTOR } ]
[ crand FLOAT ]
}
The FINISH_IDENTIFIER is optional but should proceed all other items. Any
items after the FINISH_IDENTIFIER modify or override settings given in the
IDENTIFIER. If no identifier is specified then the items modify the finish
values in the current default texture. Note that transformations are not
allowed inside a finish because finish items cover the entire surface
uniformly.
3.6.3.1 Ambient
The light you see in dark shadowed areas comes from diffuse reflection off of
other objects. This light cannot be directly modeled using ray tracing.
However we can use a trick called "ambient lighting" to simulate the light
inside a shadowed area.
Ambient light is light that is scattered everywhere in the room. It bounces
all over the place and manages to light objects up a bit even where no light
is directly shining. Computing real ambient light would take far too much
time, so we simulate ambient light by adding a small amount of white light to
each texture whether or not a light is actually shining on that texture.
This means that the portions of a shape that are completely in shadow will
still have a little bit of their surface color. It's almost as if the texture
glows, though the ambient light in a texture only affects the shape it is
used on.
Usually a single float value is specified even though the syntax calls for a
color. For example a float value of 0.3 gets promoted to the full color
vector <0.3,0.3,0.3,0.3,0.3> which is acceptible because only the r,g,b parts
are used.
The default value is very little ambient light (0.1). The value can range
from 0.0 to 1.0. Ambient light affects both shadowed and non-shadowed areas
so if you turn up the ambient value you may want to turn down the diffuse
value.
Note that this method doesn't account for the color of surrounding objects.
If you walk into a room that has red walls, floor and ceiling then your white
clothing will look pink from the reflected light. POV-Ray's ambient shortcut
doesn't account for this. There is also no way to model specular reflected
indirect illumination such as the flashlight shining in a mirror.
You may color the ambient light using one of two methods. You may specify a
color rather than a float after the ambient keyword in each finish statement.
For example
finish { ambient rgb <0.3,0.1,0.1> } //a pink ambient
Also you may specify an overall color for all ambient light using the global
ambient_light setting. The actual ambient used is:
AMBIENT = FINISH_AMBIENT * GLOBAL_AMBIENT
3.6.3.2 Diffuse Reflection Items
When light reflects off of a surface, the laws of physics say that it should
leave the surface at the exact same angle it came in. This is similar to the
way a billiard ball bounces off a bumper of a pool table. This perfect
reflection is called "specular" reflection. However only very smooth polished
surfaces reflect light in this way. Most of the time, light reflects and is
scattered in all directions by the roughness of the surface. This scattering
is called "diffuse reflection" because the light diffuses or spreads in a
variety of directions. It accounts for the majority of the reflected light we
see.
In the real world, light may come from any of three possible sources. 1)It
can come directly from actual light sources which are illuminating an object.
2)It can bounce from other objects such as mirrors via specular reflection.
For example shine a flashlight onto a mirror. 3)It can bounce from other
objects via diffuse reflections. Look at some dark area under a desk or in a
corner. Even though a lamp may not directly illuminate that spot you can
still see a little bit because light comes from diffuse reflection off of
nearby objects.
3.6.3.2.1 Diffuse
POV-Ray and most other ray tracers can only simulate directly, one of these
three types of illumination. That is the light which comes directly from the
light source which diffuses in all directions. The keyword "diffuse" is used
in a finish statement to control how much light of this direct light is
reflected via diffuse reflection. For example:
finish {diffuse 0.7}
means that 70% of the light seen comes from direct illumination from light
sources. The default value is diffuse 0.6.
3.6.3.2.2 Brilliance
The amount of direct light that diffuses from an object depends upon the
angle at which it hits the surface. When light hits at a shallow angle it
illuminates less. When it is directly above a surface it illuminates more.
The "brilliance" keyword can be used in a finish statement to vary the way
light falls off depending upon the angle of incidence. This controls the
tightness of the basic diffuse illumination on objects and slightly adjusts
the appearance of surface shininess. Objects may appear more metallic by
increasing their brilliance. The default value is 1.0. Higher values from to
about 10.0 cause the light to fall off less at medium to low angles. There
are no limits to the brilliance value. Experiment to see what works best for
a particular situation. This is best used in concert with highlighting.
3.6.3.2.3 Crand Graininess
Very rough surfaces, such as concrete or sand, exhibit a dark graininess in
their apparent color. This is caused by the shadows of the pits or holes in
the surface. The "crand" keyword can be added to cause a minor random
darkening the diffuse reflection of direct illumination. Typical values range
from "crand 0.01" to "crand 0.5" or higher. The default value is 0. For
example:
finish {crand 0.05}
The grain or noise introduced by this feature is applied on a pixel-by- pixel
basis. This means that it will look the same on far away objects as on close
objects. The effect also looks different depending upon the resolution you
are using for the rendering. For these reasons it is not a very accurate way
to model the rough surface effect, but some objects still look better with a
little crand thrown in.
In previous versions of POV-Ray there was no "crand" keyword. Any lone float
value found inside a texture {...} which was not preceded by a keyword was
interpreted as a randomness value.
NOTE: This should not be used when rendering animations. This is the one of a
few truly random features in POV-Ray, and will produce an annoying flicker of
flying pixels on any textures animated with a "crand" value.
3.6.3.3 Highlights
Highlights are the bright spots that appear when a light source reflects off
of a smooth object. They are a blend of specular reflection and diffuse
reflection. They are specular-like because they depend upon viewing angle and
illumination angle. However they are diffuse-like because some scattering
occurs. In order to exactly model a highlight you would have to calculate
specular reflection off of thousands of microscopic bumps called micro
facets. The more that micro facets are facing the viewer, the shinier the
object appears, and the tighter the highlights become. POV-Ray uses two
different models to simulate highlights without calculating micro facets.
They are the specular and phong models.
Note that specular and phong highlights are NOT mutually exclusive. It is
possible to specify both and they will both take effect. Normally, however,
you will only specify one or the other.
3.6.3.3.1 Phong Highlights
The "phong" keyword controls the amount of Phong highlighting on the object.
It causes bright shiny spots on the object that are the color of the light
source being reflected.
The Phong method measures the average of the facets facing in the mirror
direction from the light sources to the viewer.
Phong's value is typically from 0.0 to 1.0, where 1.0 causes complete
saturation to the light source's color at the brightest area (center) of the
highlight. The default phong 0.0 gives no highlight.
The size of the highlight spot is defined by the phong_size value. The larger
the phong_size, the tighter, or smaller, the highlight and the shinier the
appearance. The smaller the phong_size, the looser, or larger, the highlight
and the less glossy the appearance.
Typical values range from 1.0 (Very Dull) to 250 (Highly Polished) though any
values may be used. Default phong_size is 40 (plastic) if phong_size is not
specified. For example:
finish {phong 0.9 phong_size 60}
3.6.3.3.2 Specular Highlight
A specular highlight is very similar to Phong highlighting, but uses slightly
different model. The specular model more closely resembles real specular
reflection and provides a more credible spreading of the highlights occur
near the object horizons.
Specular's value is typically from 0.0 to 1.0, where 1.0 causes complete
saturation to the light source's color at the brightest area (center) of the
highlight. The default specular 0.0 gives no highlight.
The size of the spot is defined by the value given for roughness. Typical
values range from 1.0 (Very Rough --- large highlight) to 0.0005 (Very Smooth
--- small highlight). The default value, if roughness is not specified, is
0.05 (Plastic).
It is possible to specify "wrong" values for roughness that will generate an
error when you try to render the file. Don't use 0 and if you get errors,
check to see if you are using a very, very small roughness value that may be
causing the error. For example:
finish {specular 0.9 roughness 0.02}
3.6.3.3.3 Metallic Highlight Modifier
The keyword "metallic" may be used with phong or specular highlights. This
keyword indicates that the color of the highlights will be filtered by the
surface color instead of directly using the light_source color. Note that the
keyword has no numeric value after it. You either have it or you don't. For
example:
finish {phong 0.9 phong_size 60 metallic}
3.6.3.4 Specular Reflection
When light does not diffuse and it DOES reflect at the same angle as it hits
an object, it is called "specular reflection". Such mirror-like reflection is
controlled by the "reflection" keyword in a finish statement. For example:
finish {reflection 1.0 ambient 0 diffuse 0}
This gives the object a mirrored finish. It will reflect all other elements
in the scene. Usually a single float value is specified after the keyword
even though the syntax calls for a color. For example a float value of 0.3
gets promoted to the full color vector <0.3,0.3,0.3,0.3,0.3> which is
acceptible because only the r,g,b parts are used.
The value can range from 0.0 to 1.0. By default there is no reflection.
Adding reflection to a texture makes it take longer to render because an
additional ray must be traced. The reflected light may be tinted by
specifying a color rather than a float. For example
finish { reflection rgb <0.4,0.4,0.95> } //a light blue tint
NOTE: Although such reflection is called "specular" it is not controlled by
the POV-Ray "specular" keyword. That keyword controls a "specular" highlight.
3.6.3.5 Refraction
When light passes through a surface either into or out of a dense medium, the
path of the ray of light is bent. Such bending is called refraction. Normally
transparent or semi-transparent surfaces in POV-Ray do not refract light.
Adding "refraction 1.0" to the finish statement turns on refraction.
Note: It is recommended that you only use "refraction 0" or "refraction 1".
Values in between will darken the refracted light in ways that do not
correspond to any physical property. Many POV-Ray scenes were created with
intermediate refraction values before this "bug" was discovered so the
"feature" has been maintained. A more appropriate way to reduce the
brightness of refracted light is to change the "filter" value in the colors
specified in the pigment statement. Note also that "refraction" does not
cause the object to be transparent. Transparency is only occurs if there is a
non-zero "filter" value in the color.
The amount of bending or refracting of light depends upon the density of the
material. Air, water, crystal, diamonds all have different density and thus
refract differently. The "index of refraction" or "ior" value is used by
scientists to describe the relative density of substances. The "ior" keyword
is used in POV-Ray to specify the value. For example:
texture {
pigment { White filter 0.9 }
finish {
refraction 1
ior 1.5
}
}
The default ior value of 1.0 will give no refraction. The index of refraction
for air is 1.0, water is 1.33, glass is 1.5, and diamond is 2.4. The file
IOR.INC pre-defines several useful values for ior.
NOTE: If a texture has a filter component and no value for refraction and ior
are supplied, the renderer will simply transmit the ray through the surface
with no bending. In layered textures, the refraction and ior keywords MUST be
in the last texture, otherwise they will not take effect.
3.6.3.5.1 Light Attenuation
Light attenuation is used to model the decrease in light intensity as the
light travels through a translucent object. Its syntax is:
finish {
fade_distance FADE_DISTANCE
fade_power FADE_POWER
}
The fade_distance keyword determines the distance the light has to travel to
reach half intensity while the fade_power keyword describes how fast the
light will fall off. For realistic effects a fade power of 1 to 2 should be
used.
The attenuation is calculated by a formula similar to that used for light
source attenuation.
1
attenuation = --------------------------------------
1 + (d / FADE_DISTANCE) ^ FADE_POWER
3.6.3.5.2 Faked Caustics
The syntax is:
finish {
caustics POWER
}
3.6.3.6 Iridescence
The syntax is:
finish {
irid {
AMOUNT
thickness FLOAT
turbulence VECTOR
}
}
Iridescence, or Newton's thin film interference, simulates the effect of
light on surfaces with a microscopic transparent film overlay The effect is
like an oil slick on a puddle of water or the rainbow hues of a soap bubble
(see also "irid_wavelength" ).
This finish modifies the surface's color as a function of the angle between
the light source and the surface. Since the effect works in conjunction with
the position and angle of the light sources to the surface, it does not
behave in the same ways as a procedural pigment pattern.
The "amount" parameter is the contribution of the iridescence effect to the
overall surface color. As a rule of thumb, keep to around 0.25 (25%
contribution) or less, but experiment. If the surface is coming out too
"white", try lowering the diffuse and possibly the ambient values of the
surface.
The "thickness" parameter represents the film's thickness. This is an awkward
parameter to set, since the thickness value has no relationship to the
object's scale. Changing it affects the scale, or "busy-ness" of the effect.
A very thin film will have a high frequency of color changes, where a thick
film will have large areas of color.
The thickness of the film can be varied with the special turbulence
parameter. You can only specify turbulence amount with iridescence. The
octaves, lambda, and omega values are internally set and are not adjustable
by the user at this time.
In addition, perturbing the object's surface-normal through the use of bump
patterns will affect iridescence.
[*** This may be better off in povray.doc -dmf] For the curious, thin film
interference occurs because, when the ray hits the surface of the film, part
of the light is reflected from that surface, while a portion is transmitted
into the film. This "subsurface" ray travels through the film and eventually
reflects off the opaque substrate. The light emerges from the film slightly
out of phase with the ray that was reflected from the surface.
This phase shift creates interference, which varies with the wavelength of
the component colors, resulting in some wavelengths being reinforced, while
others are cancelled out. When these components are recombined, the result is
iridescence.
The concept used for this feature came from the book Fundamentals of
Three-Dimensional Computer Graphics, by Alan Watt (Addison-Wesley).
3.6.4 Halo
A halo is used to simulate some of the atmospheric effects that occur when
small particles interact with light or radiate on their own. Those effects
include clouds, fogs, fire, etc.
Halos are attached to an object, the so called "container object", which they
completely fill. If the object is partially or completely translucent and the
object is specified to be hollow (see "Hollow" for more details) the halo
will be visible. Thus the halo effects are limited to the space that the
object covers. This should always be kept in mind.
What the halo actually will look like depends on a lot of parameters. First
of all you have to specify which kind of effect you want to simulate. After
this you need to define the distribution of the particles. This is basically
done in two steps: a mapping function is selected and a density function is
chosen. The first function maps world coordinates space onto a
one-dimensional interval while the later describes how this linear interval
is mapped onto the final density values.
The properties of the particles, such as their color and their translucency,
are given by a color map. The density values calculated by the mapping
processes are used to determine the appropriate color using this color map.
A ray marching process is used to volume sample the halo and to accumulate
the intensities and opacity of each interval.
The following sections will describe all of the halo parameters in more
detail. The complete halo syntax is given by:
halo {
attenuating | emitting | glowing | dust
[ constant | linear | cubic | poly ]
[ planar_mapping | spherical_mapping |
cylindrical_mapping | box_mapping ]
[ dust_type DUST_TYPE ]
[ eccentricity ECCENTRICITY ]
[ max_value MAX_VALUE ]
[ exponent EXPONENT ]
[ samples SAMPLES ]
[ aa_level AA_LEVEL ]
[ aa_threshold AA_THRESHOLD ]
[ jitter JITTER ]
[ turbulence <TURBULENCE> ]
[ octaves OCTAVES ]
[ omega OMEGA ]
[ lambda LAMBDA ]
[ colour_map COLOUR_MAP ]
[ frequency FREQUENCY ]
[ phase PHASE ]
[ scale <VECTOR> ]
[ rotate <VECTOR> ]
[ translate <VECTOR> ]
}
3.6.4.1 Halo Type
The type of the halo is defined by one of the following mutually exclusive
keywords (if more than one is specified the last will be used). The default
is "attenuating".
halo {
attenuating | emitting | glowing | dust
}
The halo type determines how the light will interact with the particles
inside the container object. There are two basic categories of light
interaction: self-illuminated and illuminated. The first type includes the
"attenuating", "emitting", and "glowing" effects while the "dust" effect is
of the second type.
Those four types will be covered in detail in the next sections.
3.6.4.1.1 Attenuating
The attenuating halo, that only absorbs light passing through it, is rendered
by accumulating the particle density along a ray. The total halo color is
determined from the total, accumulated density and the specified color map
(see "Halo Color Map" for details about the color map). The background light,
i.e. the light passing through the halo, is attenuated by the total density
and added to the total halo color to get the final color of the halo.
This model is suited to render particle distributions with a high "albedo"
because the final color does not depend on the transparency of single volume
elements but only on the total transparency along the ray. The albedo of a
particle is given by the amount of light scattered by this particle in all
directions in relation to the amount of incoming light. If the particle
doesn't absorb any light the albedo is one.
Clouds and steams are two of the effects that can be rendered quite realistic
by adding enough turbulence.
3.6.4.1.2 Dust
The dust halo consists of particles that do not emit any light. They only
reflect and absorb incoming light. Its syntax is:
halo {
dust
[ dust_type DUST_TYPE ]
[ eccentricity ECCENTRICITY ]
}
As the ray marches through the dust all light coming from any light sources
is accumulated and scattered according to the dust type and the current dust
density. Since this light accumulation includes a test for occlusion, other
objects may cast shadows "into" the dust.
The same scattering types that are used with the atmosphere in "Atmosphere"
can be used with the dust (the default type is isotropic scattering). They
are:
#declare ISOTROPIC_SCATTERING = 1
#declare MIE_HAZY_SCATTERING = 2
#declare MIE_MURKY_SCATTERING = 3
#declare RAYLEIGH_SCATTERING = 4
#declare HENYEY_GREENSTEIN_SCATTERING = 5
The Henyey-Greenstein function needs the additional parameter "eccentricity"
that is describe in the section about atmosphere.
3.6.4.1.3 Emitting
Emitting halos only emit light. Every particle is a small light source that
emits some light. This light is not attenuated by the other particles because
they are assumed to be very small.
As the ray travels through the density field of an emitting halo the color of
the particles in each volume element and their differential transparency is
determined from the color map. These intensities are accumulated to get the
total color of the density field. This total intensity is added to the light
passing through the halo. The background light is attenuated by the total
density of the halo.
Since the emitted light is not attenuated it can be used to model effects
like fire, explosions, light beams, etc. By choosing a well suited color map
those effects can be rendered with a high degree of realism.
Fire is best modeled using planar mapping. Spherical mapping and high
turbulence values can be used to create explosions (it's best to use a
periodic color map and frequencies larger than one).
Emitting halos do not cast any light on other objects like light sources do,
even though they are made up of small, light-emitting particles. In order to
make them actually emit light hundreds or thousands of small light sources
would have to be used. This would slow down tracing by a degree that would
make it useless.
3.6.4.1.4 Glowing
The glowing halo is similar to the emitting halo. The difference is that the
light emitted by the particles is attenuated by the other particles. This can
be seen as a combination of the attenuating and the emitting model.
3.6.4.2 Density Mapping
The density mapping is used to map points in space onto a linear,
one-dimensional interval between 0.0 and 1.0. The different mapping types are
specified by (the default is planar mapping):
halo {
planar_mapping | spherical_mapping |
cylindrical_mapping | box_mapping
}
Since the mapping takes place in relation to the coordinate center/axis/plane
the following rule should be noticed: Halo container objects should be unit
sized objects centered at the origin. They can be transformed later to suit
the individuals needs.
3.6.4.2.1 Box Mapping
The maximum of the absolute values of each coordinate given by
r(x, y, z) = max(abs(x), abs(y), abs(z))
is used to get the interval values. Values larger than one are clipped to
one.
3.6.4.2.2 Cylindrical Mapping
The distance r(x, y, z) from the y-axis given by
r(x, y, z) = sqrt(x*x + z*z)
is used to get the interval values. Values larger than one are clipped to
one.
3.6.4.2.3 Planar Mapping
The distance r(x, y, z) from the x-z-plane given by
r(x, y, z) = abs(y)
is used to get the interval values. Values larger than one are clipped to
one.
3.6.4.2.4 Spherical Mapping
The distance r(x, y, z) from the origin given by
r(x, y, z) = sqrt(x*x + y*y + z*z)
is used to get the interval values. Values larger than one are clipped to
one.
3.6.4.3 Density Function
The density function determines how the actual density values are calculated
from the linear, one-dimensional interval that the density mapping gave. It
is specified by the following keywords:
halo {
[ constant | linear | cubic | poly ]
[ max_value MAX_VALUE ]
[ exponent EXPONENT ]
}
The individual functions f(r) are described in the following sections. They
all map the value r(x, y, z) calculated by the density mapping onto a
suitable density range between 0 and MAX_VALUE (specified with the keyword
"max_value").
3.6.4.3.1 Constant
The constant function gives the constant value MAX_VALUE regardless of the
interval value after the density mapping. Its formula is:
f(r) = MAX_VALUE
3.6.4.3.2 Linear
A linear falloff from MAX_VALUE at r=0 to 0 at r=1 can be realized with the
linear function. It is given by:
f(r) = MAX_VALUE * (1 - r)
3.6.4.3.3 Cubic
The cubic function gives a smooth blend between the maximum value MAX_VALUE
at r=0 and 0 at r=1. It is given by:
f(r) = MAX_VALUE * (2 * r - 3) * r * r + 1
This is actually a cubic spline.
3.6.4.3.4 Poly
A polynomial function can be used to get a great variety of density
functions. All have the maximum value MAX_VALUE at r=0 and the minimum value
0 at r=1. It is given by:
f(r) = MAX_VALUE * (1 - r) ^ EXPONENT
The exponent is given by the "exponent" keyword. In case of EXPONENT=0 you'll
get a linear falloff.
3.6.4.4 Halo Color Map
The density f(r), which ranges from 0.0 to MAX_VALUE, is mapped onto the
color map to get the color and differential translucency for each volume
element as the ray marches through the density field (for more details about
the color mapping see "Halo Type" ). The differential translucency determines
for each value of f(r) how much the total opacity has to be increased (or
decreased).
The color map is specified by:
halo {
[ colour_map COLOUR_MAP ]
}
The differential translucency is stored in the transmittance channel of the
map's color entries. A simple example is given by
colour_map {
[0 rgbt<1, 1, 1, 1>]
[1 rgbt<1, 1, 1, 0>]
}
In this example areas with a low density (small f(r)) will be translucent
(large differential translucency) and areas with a high density (large f(r))
will be opaque (small differential translucency).
There is no default color map.
3.6.4.5 Halo Sampling
The halo effects are calculated by marching through the density field along a
ray. At discrete steps samples are taken from the density field and evaluated
according to the color map and all other parameters. The effects of all
volume elements are accumulated to get the total effect.
The following parameters are used to tune the sampling process:
halo {
[ samples SAMPLES ]
[ aa_level AA_LEVEL ]
[ aa_threshold AA_THRESHOLD ]
[ jitter JITTER ]
}
The individual sampling parameters are described in the sections below.
3.6.4.5.1 Number of Samples
The number of samples that are taken along the ray inside the halo container
object is specified by the "samples" keyword. The greater the number of
samples the more denser the density field is sampled along the ray and the
more accurate, but slower the result will be.
The default number of samples is 10. This is sufficient for simple density
fields that don't use turbulence.
High turbulence values and dust halos normally need a large number of samples
to avoid aliasing artifacts.
3.6.4.5.2 Supersampling
The sampling is prone to alias (like the atmosphere sampling in "Atmosphere"
). One way to reduce possible aliasing artifacts is to use supersampling. If
two neighboring samples differ too much an additional sampling is taken
in-between. This process recurses until the samples are close too each other
(i.e. the values of the samples, not their distance) or the maximum recursion
level given by AA_LEVEL is reached. The threshold to kick supersampling in is
given by AA_THRESHOLD.
By default supersampling is not used. The default values for AA_THRESHOLD and
AA_LEVEL are 0.3 and 3.
3.6.4.5.3 Jitter
Jitter can be used to introduce some noise to the sampling locations. This
may help to reduce aliasing artifacts at the cost of an increased noise level
in the image. But since the human visual system is much more forgiving to
noise than it is to regular patterns, this is not much of a problem.
By default jittering is not used. The values should be smaller than 1.0.
Note that the jittering is used even if the supersampling is not used.
3.6.4.6 Halo Modifiers
This section covers all general halo modifiers. They are:
halo {
[ turbulence <TURBULENCE> ]
[ octaves OCTAVES ]
[ omega OMEGA ]
[ lambda LAMBDA ]
[ frequency FREQUENCY ]
[ phase PHASE ]
[ scale <VECTOR> ]
[ rotate <VECTOR> ]
[ translate <VECTOR> ]
}
3.6.4.6.1 Turbulence Modifier
3.6.4.6.2 Octaves Modifier
3.6.4.6.3 Omega Modifier
3.6.4.6.4 Lambda Modifier
3.6.4.6.5 Frequency Modifier
The frequency parameter adjusts the number of times the density interval is
mapped onto itself, i.e. the range from 0.0 to 1.0, before it is mapped onto
the color map. The formula doing this is:
f_new(r) = (f(r) * FREQUENCY + PHASE) modulo 1.0
Thus the halo color map will be repeated by FREQUENCY.
3.6.4.6.6 Phase Modifier
The phase parameter determines the offset at which the mapping of the density
field onto itself starts. The formula doing this is:
f_new(r) = (f(r) * FREQUENCY + PHASE) modulo 1.0
Thus the color entry for density f(r)=0 can be moved to PHASE modulo 1.0.
3.6.4.6.7 Transformation Modifiers
Halos can be transformed using the rotate, scale and translate keywords. You
have to be careful that you don't move the density field out of the container
object though.
3.6.5 Special Textures
Special textures are complex textures made up of multiple textures. The
component textures may be plain textures or may be made up of special
textures. A plain texture has just one pigment, normal and finish statement.
Even a pigment with a pigment_map is still one pigment and thus considered a
plain texture as are normals with normal_map statements.
Special textures use either a texture_map to specify a blend or pattern of
textures or they use a bitmap similar to an image_map called a material_map.
There are restrictions on using special textures. A special texture may not
be used as a default texture. See the "#default" language directive. A
special texture cannot be used as a layer in a layered texture however you
may use layered textures as any of the textures contained within a special
texture.
{/HEADER 3 Texture Maps}
In addition to specifying blended color with a color_map, or pigment_map, you
may create a blend of textures using a texture_map. The syntax for a
texture_map is identical to pigment_map except you specify a texture in each
map entry.
A texture_map is specified by...
texture{
PATTERN_TYPE
texture_map {
[ NUM_1 TEXTURE_BODY_1]
[ NUM_2 TEXTURE_BODY_2]
[ NUM_3 TEXTURE_BODY_3]
...
}
TEXTURE_MODIFIERS...
}
Where NUM_1, NUM_2... are float values between 0.0 and 1.0 inclusive. A
TEXTURE_BODY is anything that would normally appear inside a texture {...}
statement but the texture keyword and {} braces are not needed. NOTE: the []
brackets are part of the actual statement. They are not notational symbols
denoting optional parts. The brackets surround each entry in the map. There
may be from 2 to 256 entries in the map.
For example,
texture {
gradient x //this is the PATTERN_TYPE
texture_map {
[0.3 pigment{Red} finish{phong 1}]
[0.3 T_Wood11] //this is a texture identifier
[0.6 T_Wood11]
[0.9 pigment{DMFWood4} finish{Shiny}]
}
}
When the gradient x function returns values from 0.0 to 0.3 then the red
highlighted texture is used. From 0.3 to 0.6 the texture identifier T_Wood11
is used. From 0.6 up to 0.9 a blend of T_Wood11 and a shiny DMFWood4 is used.
From 0.9 on up only the shiny wood is used.
Texture maps may be nested to any level of complexity you desire. The
textures in a map may have color_map or texture_maps or any type of texture
you want.
The blended area of a texture map works by fully calculating both
contributing textures in their entirety and then linearly interpolating the
apparent colors. This means that reflection, refraction and lighting
calculations are done twice for every point. This is in contrast to using a
pigment_map and normal_map in a plain texture, where the pigment is computed,
then the normal, then reflection, refraction, and lighting are calculated
once for that point.
Entire textures may also be used with the block patterns such as checker,
hexagon and brick. For example...
texture {
checker
texture { T_Wood12 scale .8 }
texture { pigment { White_Marble } finish { Shiny } scale .5 }
}
}
Note that in the case of block patterns, the texture {...} wrapping is
required around the texture information. Also note that this syntax prohibits
the use of a layered texture however you can work around this by declaring a
texture identifier for the layered texture and referencing the identifier.
A texture_map is also used with the average pattern type. See "Average" for
details.
3.6.5.1 Tiles
Earlier versions of POV-Ray had a special texture called tiles texture that
created a checkered pattern of textures. Although it is still supported for
backwards computability, you should use checker block texture pattern
described in the previous "texture_map" section rather than tiles textures.
3.6.5.2 Material Maps
The material_map special texture extends the concept of image_map to apply to
entire textures rather than solid colors. A material_map allows you to wrap a
2-D bit-mapped texture pattern around your 3-D objects.
Instead of placing a solid color of the image on the shape like an image_map,
an entire texture is specified based on the index or color of the image at
that point. You must specify a list of textures to be used like a "texture
palette" rather than the usual color palette.
When used with mapped file types such as GIF, and some PNG and TGA images,
the index of the pixel is used as an index into the list of textures you
supply. For unmapped file types such as some PNG and TGA images, the 8 bit
value of the red component in the range 0-255 is used as an index.
If the index of a pixel is greater than the number of textures in your list
then the index is taken modulo N where N is the length of your list of
textures.
3.6.5.2.1 Specifying a Material Map
The syntax for material_map is...
texture {
material_map {
FILE_TYPE "filename"
BITMAP_MODIFIERS...
texture {...} // First used for index 0
texture {...} // Second texture used for index 1
texture {...} // Third texture used for index 2
texture {...} // Fourth texture used for index 3
// and so on for however many used.
}
TRANSFORMATION...
}
If particular index values are not used in an image then it may be necessary
to supply dummy textures. It may be necessary to use a paint program or other
utility to examine the map file's palette to determine how to arrange the
texture list.
Where FILE_TYPE is one of the following keywords gif, tga, iff, ppm, pgm,
png, or sys. This is followed by the name of the file using any valid string
expression. Several optional modifiers may follow the file specification. The
modifiers are described below. Note: Earlier versions of POV-Ray allowed some
modifiers before the FILE_TYPE but that syntax is being phased out in favor
of the syntax described here.
Filenames specified in the material_map statements will be searched for in
the home (current) directory first, and if not found, will then be searched
for in directories specified by any +L switches or Library_Path= options.
This would facilitate keeping all your material maps files in a separate
subdirectory, and specifying a library path to them. Note that any operating
system default paths are not searched unless you also specify them as a
Library_Path.
By default, the material is mapped onto the X-Y plane. The material is
"projected" onto the object as though there were a slide projector somewhere
in the -Z direction. The material exactly fills the square area from x,y
coordinates (0,0) to (1,1) regardless of the bitmap's original size in
pixels. If you would like to change this default, you may translate, rotate
or scale the texture to map it onto the object's surface as desired.
The file name is optionally followed by one or more BITMAP_MODIFIERS. See
"bitmap modifiers" for other details.
After a material_map statement but still inside the texture statement you may
apply any legal texture modifiers. Note that no other pigment, normal, finish
or halo statements may be added to the texture outside the material_map. This
is illegal:
texture {
material_map {
gif "matmap.gif"
texture {T1}
texture {T2}
texture {T3}
}
finish {phong 1.0}
}
The finish must be individually added to each texture.
Note that earlier versions of POV-Ray allowed such specifications but they
were ignored. The above restrictions on syntax were necessary for various bug
fixes. This means some POV-Ray 1.0 scenes using material_maps many need minor
modifications that cannot be done automatically with the version
compatibility mode.
The textures within a material_map texture may be layered but material_map
textures do don't work as part of a layered texture. To use a layered texture
inside a material_map you must declare it as a texture identifier and invoke
it in the texture list.
3.6.6 Layered Textures
It is possible to create a variety of special effects using layered textures.
A layered texture is one where several textures that are partially
transparent are laid one on top of the other to create a more complex
texture. The different texture layers show through the transparent portions
to create the appearance of one texture that is a combination of several
textures.
You create layered textures by listing two or more textures one right after
the other. The last texture listed will be the top layer, the first one
listed will be the bottom layer. All textures in a layered texture other than
the bottom layer should have some transparency. For example:
object {
My_Object
texture {T1} // the bottom layer
texture {T2} // a semi-transparent layer
texture {T3} // the top semi-transparent layer
}
In this example T2 shows only where T3 is transparent and T1 shows only where
T2 and T3 are transparent.
The color of underlying layers is filtered by upper layers but the results do
not look exactly like a series of transparent surfaces. If you had a stack of
surfaces with the textures applied to each, the light would be filtered
twice: once on the way in as the lower layers are illuminated by filtered
light and once on the way out. Layered textures do not filter the
illumination on the way in. Other parts of the lighting calculations work
differently as well. The result look great and allow for fantastic looking
textures but they are simply different from multiple surfaces. See STONES.INC
in the standard include files for some magnificent layered textures.
Note layered textures must use the "texture {...}" wrapped around any
pigment, normal or finish statements. Do not use multiple pigment, normal or
finish statements without putting them inside the texture statement.
Layered textures may be declared. For example:
#declare Layered_Examp=
texture {T1}
texture {T2}
texture {T3}
Then invoke it as follows:
object {
My_Object
texture {
Layer_Examp
// Any pigment, normal or finish here
// modifies the bottom layer only.
}
}
If you wish to use a layered texture in a block pattern such as checker,
hexagon, or brick or in a material_map, you must declare it first and then
reference it inside a single texture statement. A special texture cannot be
used as a layer in a layered texture however you may use layered textures as
any of the textures contained within a special texture.
3.6.7 Patterns
POV-Ray uses a method called "3D solid texturing" to define the color,
bumpiness and other properties of a surface. You specify the way that the
texture varies over a surface by specifying a pattern. Patterns are used in
pigments, normals and texture maps.
All patterns in POV-Ray are three dimensional. For every point in space, each
pattern has a unique value. Patterns do not wrap around a surface like
putting wallpaper on an object. The patterns exist in 3-d and the objects are
carved from them like carving an object from a solid block of wood or stone.
Consider a block of wood. It contains light and dark bands that are
concentric cylinders being the growth rings of the wood. On the end of the
block you see these concentric circles. Along its length you see lines that
are the veins. However the pattern exists throughout the entire block. If you
cut or carve the wood it reveals the pattern inside. Similarly an onion
consists of concentric spheres that are visible only when you slice it.
Marble stone consists of wavy layers of colored sediments that harden into
rock.
These solid patterns can be simulated using mathematical functions. Other
random patterns such as granite or bumps and dents can be generated using a
random number system and a noise function.
In each case, the x, y, z coordinate of a point on a surface is used to
compute some mathematical function that returns a float value. When used with
color maps or pigment maps, that value looks up the color of the pigment to
be used. In normal statements, the pattern function result modifies or
perturbs the surface normal vector to give a bumpy appearance. Used with a
texture map, the function result determines which combinations of entire
textures to be used.
See the sections "pigment" , "color_map" , "normal" , and "texture_map" for
more details on how to use patterns. The following sections describe each
pattern.
3.6.7.1 Agate
The agate pattern.
This pattern is a banded pattern similar to marble, but it uses a specialized
built-in turbulence function that is different from the traditional
turbulence. The traditional turbulence can be used as well but it is
generally not necessary because agate is already very turbulent. You may
control the amount of the built-in turbulence by adding the agate_turb
keyword followed by a float value. For example:
pigment {
agate
agate_turb 0.5
color_map {
...
}
}
The agate pattern uses the ramp_wave wave type by default but may use any
wave type. The pattern may be used with color_map, pigment_map, normal_map,
slope_map and texture_map.
3.6.7.2 Average
Technically average is not a pattern type but it is listed here because the
syntax is similar to other patterns. Typically a pattern type specifies how
colors or normals are chosen from a pigment map or normal map however average
tells POV-Ray to average together all of the patterns you specify. Average
was originally designed to be used in a normal statement with a normal map as
a method of specifying more than one normal pattern on the same surface.
However average may be used in a pigment statement with a pigment map, or in
a texture statement with a texture map to average colors too.
When used with pigments, the syntax is:
pigment {
average
pigment_map
{
[WEIGHT_1 PIGMENT_BODY_1]
[WEIGHT_2 PIGMENT_BODY_2]
...
[WEIGHT_n PIGMENT_BODY_n]
}
PIGMENT_MODIFIER
}
A PIGMENT_BODY is anything that would normally appear inside a pigment {...}
statement but the pigment keyword and the {} braces are not needed. NOTE: the
[] brackets are part of the actual statement. They are not notational symbols
denoting optional parts. The brackets surround each entry in the map. There
may be from 2 to 256 entries in the map. The values WEIGHT_1, WEIGHT_2, etc.
are optional float values that specify the relative weight of each pigment.
The default weight if unspecified is 1.0. All of the pigments are computed
separately, the colors are then weighted and averaged.
Similarly you may use a texture map in a texture statement. All textures are
fully computed. The resulting colors are then weighted and averaged.
When used with a normal map in a normal statement, multiple copies of the
original surface normal are created and are perturbed by each pattern. The
perturbed normals are then weighted, added and normalized.
See the sections "pigment_map" , "normal_map" , and "texture_map" for more
information.
3.6.7.3 Bozo
The bozo pattern.
The bozo pattern is a very smooth, random noise function that is
traditionally used with some turbulence to create clouds. The spotted pattern
is identical to bozo but in early versions of POV-Ray, spotted did not allow
turbulence to be added. Turbulence can now be added to any pattern so these
are redundant but both are retained for backwards compatibility. The bumps
pattern is also identical to bozo when used anywhere except in a normal
statement. When used as a normal, bumps uses a slightly different method to
perturb the normal with a similar noise function.
The bozo noise function has the following properties:
1. It's defined over 3D space i.e., it takes x, y, and z and returns the
noise value there.
2. If two points are far apart, the noise values at those points are
relatively random.
3. If two points are close together, the noise values at those points are
close to each other.
You can visualize this as having a large room and a thermometer that ranges
from 0.0 to 1.0. Each point in the room has a temperature. Points that are
far apart have relatively random temperatures. Points that are close together
have close temperatures. The temperature changes smoothly, but randomly as we
move through the room.
Now, let's place an object into this room along with an artist. The artist
measures the temperature at each point on the object and paints that point a
different color depending on the temperature. What do we get? A POV-Ray bozo
texture!
The bozo pattern uses the ramp_wave wave type by default but may use any wave
type. The pattern may be used with color_map, pigment_map, normal_map,
slope_map and texture_map.
3.6.7.4 Brick
The brick pattern.
The brick pattern generates a pattern of bricks. The bricks are offset by
half a brick length on every other row in the X and Z directions. A layer of
mortar surrounds each brick. The syntax is given by
pigment {
brick COLOR_1, COLOR_2
brick_size VECTOR
mortar FLOAT
}
where COLOR_1 is the color of the mortar, and COLOR_2 is the color of the
brick itself. If no colors are specified, a default deep red and dark gray
are used. The default size of the brick and mortar together is <8, 3, 4.5>
units. The default thickness of the mortar is 0.5 units. These values may be
changed using the optional brick_size and mortar pattern modifiers. You may
also use pigment statements in place of the colors. For example:
pigment {
brick pigment{Jade}, pigment{Black_Marble}
}
When used with normals, the syntax is
normal {
brick BUMP_FLOAT
}
Where BUMP_FLOAT is an optional bump size float value. You may also use full
normal statements. For example:
normal {
brick normal{bumps 0.2}, normal{granite 0.3}
}
When used with textures, the syntax is
texture {
brick texture{T_Gold_1A},texture{Stone12}
}
This is a block pattern which cannot use wave types, color_map, or slope_map
modifiers.
3.6.7.5 Bumps
The bumps pattern.
The bumps pattern was originally designed only to be used as a normal
pattern. It uses a very smooth, random noise function that creates the look
of rolling hills when scaled large or a bumpy orange peal when scaled small.
Usually the bumps are about 1 unit apart.
When used as a normal, bumps uses a specialized normal perturbation function.
This means that the bumps pattern cannot be used with normal_map, slope_map,
or wave type modifiers in a normal statement.
When used as a pigment pattern or texture pattern, the bumps pattern
identical to bozo or spotted and is similar to normal bumps but is not
identical as are most normals when compared to pigments. When used as pigment
or texture statements the bumps pattern uses the ramp_wave wave type by
default but may use any wave type. The pattern may be used with color_map,
pigment_map, and texture_map.
3.6.7.6 Checker
The checker pattern.
The checker pattern produces a checkered pattern consisting of alternating
squares of COLOR_1 and COLOR_2. If no colors are specified then default blue
and green colors are used.
pigment { checker COLOR_1, COLOR_2 }
The checker pattern is actually a series of cubes that are one unit in size.
Imagine a bunch of 1 inch cubes made from two different colors of modeling
clay. Now imagine arranging the cubes in an alternating check pattern and
stacking them in layer after layer so that the colors still alternated in
every direction. Eventually you would have a larger cube. The pattern of
checks on each side is what the POV-Ray checker pattern produces when applied
to a box object. Finally imagine cutting away at the cube until it is carved
into a smooth sphere or any other shape. This is what the checker pattern
would look like on an object of any kind.
You may also use pigment statements in place of the colors. For example:
pigment { checker pigment{Jade}, pigment{Black_Marble} }
When used with normals, the syntax is
normal { checker BUMP_FLOAT }
Where BUMP_FLOAT is an optional bump size float value. You may also use full
normal statements. For example:
normal {
checker normal{gradient x scale .2}, normal{gradient y scale .2}
}
When used with textures, the syntax is...
texture { checker texture{T_Wood_3A},texture{Stone12} }
This use of checker as a texture pattern replaces the special tiles texture
in previous versions of POV-Ray. You may still use tiles but it may be phased
out in future versions so checker textures are best.
This is a block pattern which cannot use wave types, color_map, or slope_map
modifiers.
3.6.7.7 Crackle
The crackle pattern.
The crackle pattern is set of random tiled polygons. With a large scale and
no turbulence it makes a pretty good stone wall or floor. With a small scale
and no turbulence it makes a pretty good crackle ceramic glaze. Using high
turbulence it makes a good marble that avoids the problem of apparent
parallel layers in traditional marble.
Mathematically, the set crackle(p)=0 is a 3D Voronoi diagram of a field of
semi random points, and crackle(p)>0 is the distance from the set along the
shortest path (A Voronoi diagram is the locus of points equidistant from
their 2 nearest neighbors from a set of disjoint points, like the membranes
in suds are to the centers of the bubbles).
The crackle pattern uses the ramp_wave wave type by default but may use any
wave type. The pattern may be used with color_map, pigment_map, normal_map,
slope_map and texture_map.
3.6.7.8 Dents
The dents pattern.
The dents pattern was originally designed only to be used as a normal
pattern. It is especially interesting when used with metallic textures, it
gives impressions into the metal surface that look like dents have been
beaten into the surface with a hammer. Usually the dents are about 1 unit
apart.
When used as a normal pattern, dents uses a specialized normal perturbation
function. This means that the dents pattern cannot be used with normal_map,
slope_map, or wave type modifiers in a normal statement.
When used as a pigment pattern or texture pattern, the dents pattern is
similar to normal dents but is not identical as are most normals when
compared to pigments. When used in pigment or texture statements the dents
pattern uses the ramp_wave wave type by default but may use any wave type.
The pattern may be used with color_map, pigment_map, and texture_map.
3.6.7.9 Gradient
The gradient pattern.
One of the simplest patterns is the gradient pattern. It is specified as
pigment {gradient VECTOR}
where VECTOR is a vector pointing in the direction that the colors blend. For
example:
pigment { gradient x } // bands of color vary as you move
// along the "x" direction.
This produces a series of smooth bands of color that look like layers of
color next to each other. Points at x=0 are the first color in the color map.
As the X location increases it smoothly turns to the last color at x=1. Then
it starts over with the first again and gradually turns into the last color
at x=2. The pattern reverses for negative values of X. Using gradient y or
gradient z makes the colors blend along the y or z axis. Any vector may be
used but x, y and z are most common.
As a normal pattern, gradient generates a saw-tooth or ramped wave
appearance. The syntax is
normal { gradient VECTOR, BUMP_FLOAT}
where the VECTOR giving the orientation is a required parameter but the
BUMP_FLOAT bump size which follows is optional.
The pattern uses the ramp_wave wave type by default but may use any wave
type. The pattern may be used with color_map, pigment_map, normal_map,
slope_map and texture_map.
3.6.7.10 Granite
The granite pattern.
This pattern uses a simple 1/f fractal noise function to give a good granite
pattern. This pattern is used with creative color maps in STONES.INC to
create some gorgeous layered stone textures.
As a normal pattern it creates an extremely bumpy surface that looks like a
gravel driveway or rough stone.
The pattern uses the ramp_wave wave type by default but may use any wave
type. The pattern may be used with color_map, pigment_map, normal_map,
slope_map and texture_map.
3.6.7.11 Hexagon
The hexagon pattern is a block pattern that generates a repeating pattern of
hexagons in the XZ plane. In this instance imagine tall rods that are
hexagonal in shape and are parallel to the Y axis and grouped in bundles like
shown in the example image. Three separate colors should be specified as
follows:
pigment {hexagon COLOR_1, COLOR_2, COLOR_3 }
_____
/ \
/ C2 \_____
|\ / \
| \_____/ C3 \
| / \ /|
/ C1 \_____/ |
|\ /| | |
| \_____/ | | |
| | | | | |
| | | | | |
| | | | | |
| | | | | |
| | | | |
| | | | |
| |
| |
The hexagon pattern.
The three colors will repeat the pattern shown above with hexagon COLOR_1
centered at the origin, COLOR_2 in the +Z direction and COLOR_3 to either
side. Each side of the hexagon is one unit long. The hexagonal "rods" of
color extend infinitely in the +Y and -Y directions. If no colors are
specified then default blue, green, and red colors are used.
You may also use pigment statements in place of the colors. For example:
pigment {
hexagon pigment { Jade },
pigment { White_Marble },
pigment { Black_Marble }
}
When used with normals, the syntax is
normal { hexagon BUMP_FLOAT }
Where BUMP_FLOAT is an optional bump size float value. You may also use full
normal statements. For example:
normal {
hexagon
normal { gradient x scale .2 },
normal { gradient y scale .2 },
normal { bumps scale .2 }
}
When used with textures, the syntax is...
texture {
hexagon
texture { T_Gold_3A },
texture { T_Wood_3A },
texture { Stone12 }
}
This is a block pattern which cannot use wave types, color_map, or slope_map
modifiers.
3.6.7.12 Leopard
The leopard pattern.
Leopard creates regular geometric pattern of circular spots.
The pattern uses the ramp_wave wave type by default but may use any wave
type. The pattern may be used with color_map, pigment_map, normal_map,
slope_map and texture_map.
3.6.7.13 Mandel
The mandel pattern computes the standard Mandelbrot fractal pattern and
projects it onto the X-Y plane. It uses the X and Y coordinates to compute
the Mandelbrot set. The pattern is specified with the keyword mandel followed
by an integer number. This number is the maximum number of iterations to be
used to compute the set. Typical values range from 10 up to 256 but any
positive integer may be used. For example:
pigment {
mandel 25
color_map {
[0.0 color Cyan]
[0.3 color Yellow]
[0.6 color Magenta]
[1.0 color Cyan]
}
scale .5
}
The value passed to the color map is computed by the formula:
value = number_of_iterations / max_iterations
When used as a normal pattern, the syntax is...
normal {
mandel ITER, BUMP_AMOUNT
}
where the required integer ITER value is optionally followed by a float bump
size.
The pattern extends infinitely in the Z direction similar to a planar image
map. The pattern uses the ramp_wave wave type by default but may use any wave
type. The pattern may be used with color_map, pigment_map, normal_map,
slope_map and texture_map.
3.6.7.14 Marble
The marble pattern.
The marble pattern is very similar to the gradient x pattern. The gradient
pattern uses a default ramp_wave wave type which means it uses colors from
the color map from 0.0 up to 1.0 at location x=1 but then jumps back to the
first color for x > 1.0 and repeats the pattern again and again. However the
marble pattern uses the triangle_wave wave type in which it uses the color
map from 0 to 1 but then it reverses the map and blends from 1 back to zero.
For example:
pigment {
gradient x
color_map {
[0.0 color Yellow]
[1.0 color Cyan]
}
}
This blends from yellow to cyan and then it abruptly changes back to yellow
and repeats. However replacing gradient x with marble smoothly blends from
yellow to cyan as the x coordinate goes from 0.0 to 0.5 and then smoothly
blends back from cyan to yellow by x=1.0.
Earlier versions of POV-Ray did not allow you to change wave types. Now that
wave types can be changed for most any pattern, the distinction between
marble and gradient x is only a matter of default wave types.
When used with turbulence and an appropriate color map, this pattern looks
like veins of color of real marble, jade or other types of stone. By default,
marble has no turbulence.
The pattern may be used with color_map, pigment_map, normal_map, slope_map
and texture_map.
3.6.7.15 Onion
The onion pattern.
Onion is a pattern of concentric spheres like the layers of an onion. Each
layer is one unit thick.
The pattern uses the ramp_wave wave type by default but may use any wave
type. The pattern may be used with color_map, pigment_map, normal_map,
slope_map and texture_map.
3.6.7.16 Quilted
The quilted pattern.
The quilted pattern was originally designed only to be used as a normal
pattern. The quilted pattern is so named because it can create a pattern
somewhat like a quilt or a tiled surface. The squares are actually 3-D cubes
that are 1 unit in size.
When used as a normal pattern it uses a specialized normal perturbation
function. This means that the quilted pattern cannot be used with normal_map,
slope_map, or wave type modifiers in a normal statement.
When used as a pigment pattern or texture pattern, the quilted pattern is
similar to normal quilted but is not identical as are most normals when
compared to pigments. When used in pigment or texture statements the quilted
pattern uses the ramp_wave wave type by default but may use any wave type.
The pattern may be used with color_map, pigment_map, and texture_map.
The two parameters, control0 and control1 are used to adjust the curvature of
the "seam" or "gouge" area between the "quilts". The syntax is:
normal {
quilted AMOUNT
control0 FLOAT
control1 FLOAT
}
The values should generally be kept to around the 0.0 to 1.0 range. The
default value is 1.0 if none is specified. Think of this "gouge" between the
tiles in cross-section as a sloped line:
__ ___
\ / <-control1
\ /
\ /
\___/ <- control0
Quilted pattern controls.
This straight slope can be made to curve by adjusting the two control values.
The control values adjust the slope at the top and bottom of the curve. A
control values of 0 at both ends will give a linear slope, as shown above,
yielding a hard edge. A control value of 1 at both ends will give an "s"
shaped curve, resulting in a softer, more rounded edge.
3.6.7.17 Radial
The radial pattern.
The radial pattern is a radial blend that wraps around the +Y axis. The color
for value 0.0 starts at the +X direction and wraps the color map around from
east to west with 0.25 in the -Z direction, 0.5 in -X, 0.75 at +Z and back to
1.0 at +X. Typically the pattern is used with a frequency modifier to create
multiple bands that radiate from the Y axis.
The pattern uses the ramp_wave wave type by default but may use any wave
type. The pattern may be used with color_map, pigment_map, normal_map,
slope_map and texture_map.
3.6.7.18 Ripples
The ripples pattern.
The ripples pattern was originally designed only to be used as a normal
pattern. It makes the surface look like ripples of water. The ripples radiate
from 10 random locations inside the unit cube area <0,0,0> to <1,1,1>. Scale
the pattern to make the centers closer or farther apart.
Usually the ripples from any given center are about 1 unit apart. The
frequency keyword changes the spacing between ripples. The phase keyword can
be used to move the ripples outwards for realistic animation.
The number of ripple centers can be changed with the global parameter
global_setting {number_of_waves FLOAT} somewhere in the scene. This affects
the entire scene. You cannot change the number of wave centers on individual
patterns. See "global_settings" for details.
When used as a normal pattern, ripples uses a specialized normal perturbation
function. This means that the ripples pattern cannot be used with normal_map,
slope_map, or wave type modifiers in a normal statement.
When used in pigment or texture statements the ripples pattern uses the
ramp_wave wave type by default but may use any wave type. The pattern may be
used with color_map, pigment_map, and texture_map.
3.6.7.19 Spiral1
The spiral1 pattern.
The spiral1 pattern creates a spiral that winds around the y-axis similar to
a screw. Its syntax is:
pigment {
spiral1 NUMBER_OF_ARMS
}
The NUMBER_OF_ARMS-value determins how may "arms" are winding around the y
axis.
The pattern uses the triangle_wave wave type by default but may use any wave
type. The pattern may be used with color_map, pigment_map, normal_map,
slope_map and texture_map.
3.6.7.20 Spiral2
The spiral2 pattern.
The spiral2 pattern is a modification of the spiral1 pattern with an
extraordinary look.
The pattern uses the triangle_wave wave type by default but may use any wave
type. The pattern may be used with color_map, pigment_map, normal_map,
slope_map and texture_map.
3.6.7.21 Spotted
The spotted pattern.
The spotted pattern is identical to the bozo pattern. Early versions of
POV-Ray did not allow turbulence to be used with spotted. Now that any
pattern can use turbulence there is no difference between bozo and spotted.
See "bozo" for details.
3.6.7.22 Waves
The waves pattern.
The waves pattern was originally designed only to be used as a normal
pattern. The waves pattern looks similar to the ripples pattern except the
features are rounder and broader. The effect is to make waves that look more
like deep ocean waves. The waves radiate from 10 random locations inside the
unit cube area <0,0,0> to <1,1,1>. Scale the pattern to make the centers
closer or farther apart.
Usually the waves from any given center are about 1 unit apart. The frequency
keyword changes the spacing between waves. The phase keyword can be used to
move the waves outwards for realistic animation.
The number of ripple centers can be changed with the global parameter
global_setting {number_of_waves FLOAT} somewhere in the scene. This affects
the entire scene. You cannot change the number of wave centers on individual
patterns. See "global_settings" for details.
When used as a normal pattern, waves uses a specialized normal perturbation
function. This means that the waves pattern cannot be used with normal_map,
slope_map, or wave type modifiers in a normal statement.
When used in pigment or texture statements the waves pattern uses the
ramp_wave wave type by default but may use any wave type. The pattern may be
used with color_map, pigment_map, and texture_map.
3.6.7.23 Wood
The wood pattern.
The wood pattern consists of concentric cylinders centered on the Z axis.
When appropriately colored, the bands look like the growth rings and veins in
real wood. Small amounts of turbulence should be added to make it look more
realistic. By default, wood has no turbulence.
Unlike most patterns, the wood pattern uses the triangle_wave wave type by
default. This means that like marble, wood uses color map values 0.0 to 1.0
then repeats the colors in reverse order from 1.0 to 0.0. However you may use
any wave type. The pattern may be used with color_map, pigment_map,
normal_map, slope_map and texture_map.
3.6.7.24 Wrinkles
The wrinkles pattern.
The wrinkles pattern was originally designed only to be used as a normal
pattern. It uses a 1/f noise pattern similar to granite but the features in
wrinkles are sharper. The pattern can be used to simulate wrinkled cellophane
or foil. It also makes an excellent stucco texture.
When used as a normal pattern it uses a specialized normal perturbation
function. This means that the wrinkles pattern cannot be used with
normal_map, slope_map, or wave type modifiers in a normal statement.
When used as a pigment pattern or texture pattern, the wrinkles pattern is
similar to normal wrinkles but is not identical as are most normals when
compared to pigments. When used in pigment or texture statements the wrinkles
pattern uses the ramp_wave wave type by default but may use any wave type.
The pattern may be used with color_map, pigment_map, and texture_map.
3.6.8 Pattern Modifiers
Pattern modifiers are statements or parameters which modify how a pattern is
evaluated or tells what to do with the pattern. The modifiers color_map and
pigment_map apply only to pigments. See "pigment" . The modifiers bump_size,
slope_map and normal_map apply only to normals. See "normal" . The
texture_map modifier can only be used with textures. See "texture_map" .
The pattern modifiers in the following section can be used with pigment,
normal or texture patterns.
3.6.8.1 Transforming Patterns
The most common pattern modifiers are the transformation modifiers translate,
rotate, scale, and matrix. For details on these commands see
"Transformations" .
These modifiers may be placed inside pigment, normal and texture statements
to change the position, size and orientation of the patterns.
In general the order of transformations relative to other pattern modifiers
such as turbulence, color_map and other maps is not important. For example
scaling before or after turbulence makes no difference. The turbulence is
done first, then the scaling regardless of which is specified first. However
the order in which transformations are performed relative to warp statements
is important. See "warps" for details.
3.6.8.2 Frequency and Phase
The frequency and phase modifiers act as a type of scale and translate
modifiers for color_map, pigment_map, normal_map, slope_map and texture_map.
This discussion uses color_map as an example but the same principles apply to
pigment_map, ormal_map, slope_map and texture_map.
The frequency keyword adjusts the number of times that a color map repeats
over one cycle of a pattern. For example gradient x covers color map values 0
to 1 over the range x=0 to x=1. By adding frequency 2.0 the color map repeats
twice over that same range. The same effect can be achieved using scale x*0.5
so the frequency keyword isn't that useful for patterns like gradient.
However the radial pattern wraps the color map around the +Y axis once. If
you wanted two copies of the map (or 3 or 10 or 100) you'd have to build a
bigger map. Adding frequency 2.0 causes the color map to be used twice per
revolution. Try this:
pigment {
radial
color_map{[0.5 color Red][0.5 color White]}
frequency 6
}
The result is 6 sets of red and white radial stripes evenly spaced around the
object.
The float after frequency can be any value. Values greater than 1.0 causes
more than one copy of the map to be used. Values from 0.0 to 1.0 cause a
fraction of the map to be used. Negative values reverses the map.
The phase value causes the map entries to be shifted so that the map starts
and ends at a different place. In the example above if you render successive
frames at phase 0 then phase 0.1, phase 0.2 etc you could create an animation
that rotates the stripes. The same effect can be easily achieved by rotating
the radial pigment using rotate y*Angle but there are other uses where phase
can be handy.
Sometimes you create a great looking gradient or wood color map but you want
the grain slightly adjusted in or out. You could re-order the color map
entries but that's a pain. A phase adjustment will shift everything but keep
the same scale. Try animating a mandel pigment for a color palette rotation
effect.
Frequency and phase have no effect on block patterns checker, brick and
hexagon nor do they effect image_map, bump_map or material_map. They also
have no effect in normal statements when used with bumps, dents, quilted, or
wrinkles because these normal patterns cannot use normal_map or slope_map.
They can be used with normal patterns ripples and waves even though these two
patterns cannot use normal_map or slope_map either. When used with ripples or
waves, frequency adjusts the space between features and phase can be adjusted
from 0.0 to 1.0 to cause the ripple or waves to move relative to their center
for animating the features.
These values work by applying the following formula:
NEW_VALUE = fmod ( OLD_VALUE * FREQUENCY + PHASE, 1.0 )
3.6.8.3 Waveform
Most patterns that take color_map, pigment_map, slope_map, normal_map or
texture_map, use the entries in the map in order from 0.0 to 1.0 however the
wood and marble patterns use the map from 0.0 to 1.0 and then reverses it and
runs it from 1.0 to 0.0. These differences can easily be seen when using
these patterns are used as normal patterns with no maps. Patterns such as
gradient or onion generate a grove or slot that looks like a ramp that drops
off sharply. This is called a ramp_wave wave type. However wood and marble
slope upwards to a peak, then slope down again in a triangle_wave. In
previous versions of POV-Ray there was no way to change the wave types. You
could simulate a triangle wave on a ramp wave pattern by duplicating the map
entries in reverse, however there was no way to use a ramp wave on wood or
marble.
Now any pattern that takes a map can have the default wave type overridden.
For example:
pigment { wood color_map { MyMap } ramp_wave }
Also available are sine_wave and scallop_wave types. These types are of most
use in normal patterns as a type of built-in slope map. The sine_wave takes
the zig-zag of a ramp_wave and turns it into a gentle rolling wave with
smooth transitions. The scallop_wave uses the absolute value of the sine wave
which looks like corduroy when scaled small or like a stack of cylinders when
scaled larger.
Although these any of these wave types can be used for pigments, normals or
textures, the sine_wave and scallop_wave types are not as noticeable on
pigments or textures as they are for normals.
Wave types have no effect on block patterns checker, brick and hexagon nor do
they effect image_map, bump_map or material_map. They also have no effect in
normal statements when used with bumps, dents, quilted, or wrinkles because
these normal patterns cannot use normal_map or slope_map.
3.6.8.4 Turbulence
The keyword turbulence followed by a float or vector may be used to stir up
any pigment, normal, texture, irid or halo. A number of optional parameters
may be used with turbulence to control how it is computed. For example:
pigment {
wood color_map { MyMap }
turbulence TURB_VECTOR
octaves FLOAT
omega FLOAT
lambda FLOAT
}
Typical turbulence values range from the default 0.0 which is no turbulence
to 1.0 or more which is very turbulent. If a vector is specified then
different amounts of turbulence are applied in the x, y and z directions. For
example
turbulence <1.0, 0.6, 0.1>
has much turbulence in the x direction, a moderate amount in the y direction
and a small amount in the z direction.
Turbulence uses a random noise function called DNoise. This is similar to the
noise used in the bozo pattern except that instead of giving a single value
it gives a direction. You can think of it as the direction that the wind is
blowing at that spot. Points close together generate almost the same value
but points far apart are randomly different.
In general the order of turbulence parameters relative to other pattern
modifiers such as transformations, color_map and other maps is not important.
For example scaling before or after turbulence makes no difference. The
turbulence is done first, then the scaling regardless of which is specified
first. See "warps" for a way to work around this behavior.
Turbulence uses DNoise to push a point around in several steps called
octaves. We locate the point we want to evaluate, then push it around a bit
using turbulence to get to a different point then look up the color or
pattern of the new point.
It says in effect "Don't give me the color at this spot... take a few random
steps in different directions and give me that color." Each step is typically
half as long as the one before. For example:
P ------------------------->
First Move /
/
/
/Second
/ Move
/
______/
\
\
Q - Final point.
Turbulence random walk.
The magnitude of these steps is controlled by the turbulence value. There are
three additional parameters which control how turbulence is computed. They
are octaves, lambda and omega. Each is optional. Each is followed by a single
float value. Each has no effect when there is no turbulence.
3.6.8.5 Octaves
The octaves value controls the number of steps of turbulence that are
computed. Legal values range from 1 to 10. The default value of 6 is a fairly
high value; you won't see much change by setting it to a higher value because
the extra steps are too small. Float values are truncated to integer. Using
smaller number of octaves gives a gentler, wavy turbulence and computes
faster. Higher octaves create more jagged or fuzzy turbulence and takes
longer to compute.
3.6.8.6 Lambda
The lambda parameter controls how statistically different the random move of
an octave is compared to its previous octave. The default value is 2.0 which
is quite random. Values close to lambda 1.0 will straighten out the
randomness of the path in the diagram above. The zig-zag steps in the
calculation are in nearly the same direction. Higher values can look more
"swirly" under some circumstances.
3.6.8.7 Omega
The omega value controls how large each successive octave step is compared to
the previous value. Each successive octave of turbulence is multiplied by the
omega value. The default omega 0.5 means that each octave is 1/2 the size of
the previous one. Higher omega values mean that 2nd, 3rd, 4th and up octaves
contribute more turbulence giving a sharper, "crinkly" look while smaller
omegas give a fuzzy kind of turbulence that gets blurry in places.
3.6.8.8 Warps
The warp statement is a pattern modifier that is similar to turbulence.
Turbulence works by taking the pattern evaluation point and pushing it about
in a series of random steps, however warps push the point in very
well-defined, non-random, geometric ways. The warp statement also overcomes
some limitations of traditional turbulence and transformations by giving the
user more control over the order in which turbulence, transformation and warp
modifiers are applied to the pattern.
Currently there are three types of warps but the syntax was designed to allow
future expansion. The first two, the repeat warp and the black_hole warp are
new features for POV-Ray that modify the pattern in geometric ways. The other
warp provides an alternative way to specify turbulence.
The syntax for using a warp statement in a pigment is
pigment {
PATTERN_TYPE
PIGMENT_MODIFIERS...
warp { WARP_ITEMS...}
OTHER_PIGMENT_MODIFIERS...
}
Similarly warps may be used in normals and textures. You may have as many
separate warp statements as you like in each pattern. The placement of warp
statements relative to other modifiers such as color_map or turbulence is not
important. However placement of warp statements relative to each other and to
transformations is significant. Multiple warps and transformations are
evaluated in the order in which you specify them. For example if you
translate, then warp or warp, then translate, the results can be different.
3.6.8.8.1 Black Hole Warp
A black hole is so named because of its similarity to real black holes. Just
like the real thing, you cannot actually see a black hole. The only way to
detect its presence is by the effect it has on things that surround it.
Unlike the real thing, however, it won't swallow you up and compress your
entire body to an volume of, say, 2.0*10^-10 microns in diameter if you get
too close (We're working on that part).
Take, for example, a woodgrain. Using POV-Ray's normal turbulence and other
texture modifier functions, you can get a nice, random appearance to the
grain. But in its randomness it is regular --- it is regularly random !
Putting in a black hole allows you to create a localised disturbance in a
woodgrain in either one or multiple locations. The black hole can have the
effect of either 'sucking' the surrounding texture into itself (like the real
thing) or 'pushing' it away. In the latter case, applied to a woodgrain, it
would look to the viewer as if there were a knothole in the wood. In this
text we use a Woodgrain regularly as an example, because it is ideally
suitable to explaining Black Holes. However, Black Holes may in fact be used
with any texture.
The effect that the black hole has on the texture can be specified; by
default, it 'sucks' with the strength calculated expotentially
(inverse-square). You can change this if you like.
Black Holes may be used anywhere a Warp is permitted. The syntax is:
warp
{
black_hole <CENTER>, RADIUS
[falloff VALUE]
[strength VALUE]
[repeat <VECTOR>]
[turbulence <VECTOR>]
[inverse]
}
Some examples are given by
warp
{
black_hole <0, 0, 0>, 0.5
}
warp
{
black_hole <0.15, 0.125, 0>, 0.5
falloff 7
strength 1.0
repeat <1.25, 1.25, 0>
turbulence <0.25, 0.25, 0>
inverse
}
warp
{
black_hole <0, 0, 0>, 1.0
falloff 2
strength 2
inverse
}
In order to fully understand how a black hole works, it is important to know
the theory behind it. A black hole (or any warp) works by taking a point and
'perturbing' it to another location. The amount of perturbation depends on
the strength of the black hole at the original point passed in to it. The
amount of perturbation directly relates to the amount of visual movement that
you can see occur in a texture. The stronger the black hole at the input
co-ordinate, the more that original co-ordinate is moved to another location
(either closer to or further away from the center of the black hole.)
Movement always occurs on the vector that exists between the input point and
the center of the black hole (which I will now abbreviate BH for brevity).
Black Holes are considered to be spheres. For a point to be affected by a BH,
it must be within the sphere's volume.
Suppose you have a BH at <1,1,1>, and a point at <1,2,1>. If this point is
perturbed by a total amount of +1 unit, then its new location is <1,3,1>,
which is on a direct line extrapolated from the vector between <1,1,1> and
<1,2,1>. In this case the point is 'pushed' away from the BH, which is not
normal behaviour but is good for demonstration purposes.
The internal properties of a black hole are as follows.
Center The center of the black hole.
Radius Its radius.
Falloff The power of two by which the effect falls off (default
2.)
Strength The magnitude of the transformation effect (see below.)
Inverted If set, 'push' points away instead of 'pulling' them in.
Repeat If set, we have many black holes instead of one.
Turbulence If set, each new repeated BH's position is uncertain.
Repeat_Vector The <x,y,z> factor to repeat by.
Turbulence_Vector The maximum <x,y,z> factor for turbulence randomness.
Each of these are discussed below.
Center: A vector defining the center of the sphere that represents the black
hole. If the BH has Repeat set, it is the offset within each block.
Radius: A number giving the length, in units, of the radius of the sphere
that represents the black hole.
If a point is not within radius units of <center>, it cannot be affected by
the BH and will not be perturbed.
Falloff: The power by which the effect of the black hole falls off. The
default is two. The force of the black hole at any given point, before
applying the 'Strength' modifier, is as follows.
First, convert the distance from the point to the center to a proportion (0
to 1) that the point is from the edge of the black hole. A point on the
perimeter of the black hole will be 0.0 ; a point at the centre will be 1.0 ;
a point exactly halfway will be 0.5, and so forth.
Mentally you can consider this to be a 'closeness' factor. A closeness of 1.0
is as close as you can get to the center (i.e. *at* the center), a closeness
of 0.0 is as far away as you can get from the center and still be inside the
black hole, and a closeness of 0.5 means the point is exactly halfway between
the two.
Call this value 'C'. Raise C to the power specified in 'Falloff'. By default
Falloff
is 2, so this is C^2 or C squared. The resulting value is the force of the
black hole at that exact location and is used, after applying the 'Strength'
scaling factor as described below, to determine how much the point is
perturbed in space.
For example, if C is 0.5, then the force is 0.5^2, or 0.25. If C is 0.25, the
force is 0.125. But if C is exactly 1.0, the force is 1.0.
Recall that as C gets smaller, the point is farther from the center of the
black hole. Using the default power of 2, you can see that as C reduces, the
force reduces expotentially in an inverse-square relationship.
Put in plain english, it means that the force is much stronger (by a power of
two) towards the center than it is at the outside.
By increasing Falloff, you can increase the magnitude of the falloff ; a
large value will mean points towards the perimeter will hardly be affected at
all and points towards the center will be affected strongly.
A value of 1.0 for falloff will mean that the effect is linear ; a point that
is exactly halfway to the center of the black hole will be affected by a
force of exactly 0.5.
A value of Falloff of less than one but greater than zero means that as you
get closer to the outside, the force *increases* rather than decreases. This
can have some uses but there is a side effect ; recall that the effect of a
black hole ceases outside its perimiter. This means that points just within
the permiter will be affected strongly and those just outside not at all.
This would lead to a visible border, shaped as a sphere.
A value for Falloff of 0 would mean that the force would be 1.0 for all
points within the BH, since any number > 0 raised to the power of 0 is 1.0.
The magnitude of the movement of the point is determined basically by the
value of force after scaling. We'll consider scaling later. Lets take an
example.
Suppose we have a black hole of radius 2.0, and a point that is exactly 1.0
units from the center. That means it is exactly half-way to the center and
that C would be 0.5. If we use the default falloff of 2, the force at that
point is 0.5^2, or 0.25. What this means is that we must move the point by
0.25 of its distance from the center. In this case it is 1.0 units from the
center, so we move it by 1.0*0.25, or 0.25 units. This gives a final distance
of 1.0-(1.0*0.25) or 0.75 units from the center, on a direct line in 3D space
between the original position and the center.
If the point were part of, say, a wood grain, the wood grain would appear to
bend towards the (invisible) center of the BH. If the 'Inverse' flag were
set, however, it would be 'pushed' away, meaning its final position would be
1.0+(1.0*0.25), or 1.25 units from the center.
Strength: The 'Strength' gives you a bit more control over how much a point
is perturbed by the black hole. Basically, the force of the black hole (as
determined above) is multipled by the value of Strength, which defaults to
1.0. If you set Strength to 0.5, for example, all points within the black
hole will be moved by only half as much as they would have been. If you set
it to 2.0, they will be moved twice as much.
There is a rider to the latter example, though - the movement is clipped to a
maximum of the points original distance from the center. That is to say, a
point that is 0.75 units from the center may only be moved by a maximum of
0.75 units either towards the center or away from it, regardless of the value
of Strength. The result of this clipping is that you will have an 'exclusion'
area near the centre of the black hole where all points whose final force
value exceeded or equalled 1.0 were moved by a fixed amount.
Inverted: If Inverted is set, points are 'pushed' away from the center
instead of being pulled in.
Repeat: Repeat allows you to simulate the effect of many black holes without
having to explicitly declare them. Repeat is a vector that tells POV-Ray to
use this black hole at multiple locations.
If you're not interested in the theory behind all this, just skim this next
text and use the values given in the summary below.
Using repeat logically divides your scene up into cubes, the first being
located at <0,0,0> and going to <repeat>. i.e. suppose your repeat vector was
<1,5,2>, the first cube would be from <0,0,0> to <1,5,2>. These repeat, so
there would be one at <-1,-5,-2>, <1,5,2>, <2,10,4>, and so forth in all
directions, ad infinitum.
Instead of the center of the black hole specifying an absolute location in
your scene, when you use repeat, the center is an offset into each block. It
is only possible to use positive offsets ; using negative values will produce
undefined results.
Suppose your center was <0.5,1,0.25> and the repeat vector is <2,2,2>. This
gives us a block at <0,0,0> and <2,2,2>, etc. The centers of the BH's for
these blocks would be <0,0,0> + <0.5,1.0,0.25> i.e. <0.5,1.0,0.25>, and
<2,2,2> + <0.5,1.0,0.25>, i.e. <2,5,3.0,2.25>.
Due to the way repeats are calculated internally, there is a restriction on
the values you specify for the repeat vector. Basically, each black hole must
be totally enclosed within each block (or cube), with no part crossing into a
neighbouring one. This means that, for each of the X, Y and Z dimensions
the offset of the center may not be less than the radius, and the repeat
value for that dimension must be >= the center plus the radius
since any other values would allow the black hole to cross a boundary. Put
another way, for each of X, Y and Z
radius <= offset of center <= repeat - radius
If the repeat vector in any dimension is too small to fit this criteria, it
will be increased and a warning message issued. If the center is less than
the radius it will also be moved but no message will be issued.
Note that none of the above should be read to mean that you can't overlap
black holes. You most certainly can and in fact this can produce some most
useful effects. The restriction only applies to elements of the *same* black
hole which is repeating. You can declare a second black hole that also
repeats, and its elements can quite happily overlap the first and causing the
appropriate interactions.
It is legal for the repeat value for any dimension to be 0, meaning that
POV-Ray will not repeat the black hole in that direction.
Turbulence: Turbulence can only be used with repeat. It allows an element of
randomness to be inserted into the way the black holes repeat, to cause a
more 'natural' look. A good example would be an array of knotholes in wood
--- it would look rather artificial if each knothole were an exact distance
from the previous.
The 'turbulence vector' is a measurement that is added to each individual
back hole in an array, after each axis of the vector is multipled by a
different
random amount ranging from 0 to 1.
For example, suppose you have a repeating element of a BH that is supposed to
be at <2,2,2>. You have specified an turbulence vector of <4,5,3>, meaning
you want the position to be able to vary by no more than 1.0 units in the X
direction, 3.0 units in the Y direction and 2.0 in Z. This means that the
valid ranges of the new position are as follows
X c Z can be from 2 to 5.
The resulting actual position of the black hole's center for that particular
repeat element is random (but consistent, so renders will be repeatable) and
somewhere within the above co-ordinates.
There is a rider on the use of turbulence, which basically is the same as
that of the repeat vector ; you can't specify a value which would cause a
black hole to potentially cross outside of its particular block.
Since POV-Ray doesn't know in advance how much a position will be changed due
to the random nature of the changes, it enforces a rule that is similar to
the one for repeat, except it adds the maximum possible variation for each
axis to the center. For example, suppose you had a black hole with a center
of <1.0, 1.0, 1.0>, radius of 0.5, and a turbulence of <0.5, 0.25, 0> ---
normally, the mimimum repeat would be <1.5, 1.5, 1.5>. However, now we take
into account the turbulence, meaning the minimum repeat vector is actually
<2.0, 1.75, 1.5>.
Repeat summarized: For each of X, Y and Z, the offset of the center must be
>= radius, and the value of the repeat must be >= center + radius +
turbulence, the exception being that repeat may be 0 for any dimension, which
means do not repeat in that direction.
3.6.8.8.2 Repeat Warp
The repeat warp causes a section of the pattern to be repeated over and over.
It takes a slice out of the pattern and makes multiple copies of it
side-by-side. The warp has many uses but was originally designed to make it
easy to model wood veneer textures. Veneer is made by taking very thin slices
from a log and placing them side-by-side on some other backing material. You
see side-by-side nearly identical ring patterns but each will be a slice
perhaps 1/32th of an inch deeper.
The syntax for a repeat warp is
warp { repeat VECTOR offset VECTOR flip VECTOR }
The repeat vector specifies the direction in which the pattern repeats and
the width of the repeated area. This vector must lie entirely along an axis.
In other words, two of its three components must be 0. For example:
pigment {
wood
warp {repeat 2*x}
}
which means that from x=0 to x=2 you get whatever the pattern usually is. But
from x=2 to x=4 you get the same thing exactly shifted 2 units over in the x
direction. To evaluate it you simply take the X-coordinate modulo 2.
Unfortunately you get exact duplicates which isn't very realistic. The
optional offset vector tells how much to translate the pattern each time it
repeats. For example
pigment {
wood
warp {repeat x*2 offset z*0.05}
}
this means that we slice the first copy from x=0 to x=2 at z=0 but at x=2 to
x=4 we offset to z=0.05. In the 4 to 6 interval we slice at z=0.10. At the
Nth copy we slice at z*N*0.05. Thus each copy is slightly different. There
are no restrictions on the offset vector.
Finally the flip vector causes the pattern to be flipped or mirrored every
other copy of the pattern. The first copy of the pattern in the positive
direction from the axis is not flipped; the next farther is; the next is not,
etc. The flip vector is a 3 component x,y,z vector but each component is
treated as a boolean value that tells if you should or should not flip along
a given axis. For example:
pigment {
wood
warp {repeat 2*x flip <1,1,0>}
}
means that every other copy of the pattern will be mirrored about the X and Y
axis but not the Z axis. A non-zero value means flip and zero means do not
flip about that axis. The magnitude of the values in the flip vector doesn't
matter.
3.6.8.8.3 Turbulence Warp
The POV-Ray language contains an ambiguity and limitation on the way you
specify turbulence and transformations such as translate, rotate, scale and
matrix transforms. Usually the turbulence is done first. Then ALL translate,
rotate, scale and matrix operations are always done after turbulence
regardless of the order in which you specify them. For example this
pigment {
wood
scale .5
turbulence .2
}
works exactly the same as
pigment {
wood
turbulence .2
scale .5
}
The turbulence is always first. A better example of this limitation is with
uneven turbulence and rotations.
pigment {
wood
turbulence 0.5*y
rotate z*60
}
// as compared to
pigment {
wood
rotate z*60
turbulence 0.5*y
}
The results will be the same either way even though you'd think it should
look different.
We cannot change this basic behavior in POV-Ray now because lots of scenes
would potentially render differently if suddenly the order transformation vs
turbulence suddenly mattered when in the past, it didn't.
However, by specifying our turbulence inside warp statement you tell POV-Ray
that the order in which turbulence, transformations and other warps are
applied is significant. Here's an example of a turbulence warp.
warp { turbulence <0,1,1> octaves 3 lambda 1.5 omega 0.3 }
The significance is that this
pigment {
wood
translate <1,2,3> rotate x*45 scale 2
warp { turbulence <0,1,1> octaves 3 lambda 1.5 omega 0.3 }
}
produces different results than this...
pigment {
wood
warp { turbulence <0,1,1> octaves 3 lambda 1.5 omega 0.3 }
translate <1,2,3> rotate x*45 scale 2
}
You may specify turbulence without using a warp statement. However you cannot
control the order in which they are evaluated unless you put them in a warp.
The evaluation rules are as follows:
1) First any turbulence not inside a warp statement is applied regardless
of the order in which it appears relative to warps or transformations.
2) Next each warp statement, translate, rotate, scale or matrix one-by-one,
is applied in the order the user specifies. If you want turbulence done
in a specific order, you simply specify it inside a warp in the proper
place.
3.6.8.9 Bitmap modifiers
A bitmap modifier is a modifier used inside an "image_map" , "bump_map" or
"material_map" to specify how the 2-D bitmap is to be applied to the 3-D
surface. Several bitmap modifiers apply to specific kinds of maps and they
are covered in the appropriate sections. The bitmap modifiers discussed in
the following sections are applicable to all three types of bitmaps.
3.6.8.9.1 The once Option
Normally there are an infinite number of repeating image_maps, bump_maps, or
material_maps created over every unit square of the X-Y plane like tiles. By
adding the keyword once after a file name, you can eliminate all other copies
of the map except the one at (0,0) to (1,1). In image_maps, areas outside
this unit square are treated as fully transparent. In bump_maps, areas
outside this unit square are left flat with no normal modification. In
material_maps, areas outside this unit square are textured with the first
texture of the texture list.
For example:
image_map {
gif "mypic.gif"
once
}
3.6.8.9.2 The "map_type" Option
The default projection of the bump onto the X-Y plane is called a planar map
type . This option may be changed by adding the map_type keyword followed by
a number specifying the way to wrap the bump around the object.
A map_type 0 gives the default planar mapping already described.
A map_type 1 is a spherical mapping. It assumes that the object is a sphere
of any size sitting at the origin. The Y axis is the north/south pole of the
spherical mapping. The top and bottom edges of the bitmap just touch the pole
regardless of any scaling. The left edge of the bitmap begins at the positive
X axis and wraps the pattern around the sphere from "west" to "east" in a -Y
rotation. The pattern covers the sphere exactly once. The once keyword has no
meaning for this type.
With map_type 2 you get a cylindrical mapping. It assumes that a cylinder of
any diameter lies along the Y axis. The bump pattern wraps around the
cylinder just like the spherical map but remains 1 unit tall from y=0 to y=1.
This band of the pattern is repeated at all heights unless the once keyword
is applied.
Finally map_type 5 is a torus or donut shaped mapping. It assumes that a
torus of major radius 1 sits at the origin in the X-Z plane. The pattern is
wrapped around similar to spherical or cylindrical maps. However the top and
bottom edges of the map wrap over and under the torus where they meet each
other on the inner rim.
Types 3 and 4 are still under development.
For example:
sphere{<0,0,0>,1
pigment{
image_map {
gif "world.gif"
map_type 1
}
}
}
3.6.8.9.3 The interpolate Option
Adding the interpolate keyword can smooth the jagged look of a bitmap. When
POV-Ray asks an image_map color or a bump amount for a bump map, it often
asks for a point that is not directly on top of one pixel, but sort of
between several different colored pixels. Interpolations returns an
"in-between" value so that the steps between the pixels in the map will look
smoother.
Although interpolate is legal in material_maps, the color index is
interpolated before the texture is chosen. It does not interpolate the final
color as you might hope it would. In general, interpolation of material_map
serves no useful purpose but this may be fixed in future versions.
There are currently two types of interpolation:
Normalized Distance -- interpolate 4
Bilinear -- interpolate 2
For example:
image_map {
gif "mypic.gif"
interpolate 2
}
Default is no interpolation. Normalized distance is the slightly faster of
the two, bilinear does a better job of picking the between color. Normally,
bilinear is used.
If your map looks jaggy, try using interpolation instead of going to a higher
resolution image. The results can be very good.
3.7 Atmospheric Effects
Atmospheric effects are a loosely-knit group of features that affect the
background and/or the atmosphere enclosing the scene. POV-Ray includes the
ability to render a number of atmospheric effects, such as fog, haze, mist,
rainbows, and skies.
3.7.1 Atmosphere
Computer generated images normally assume a vacuum space that does not allow
the rendering of natural phenomena like smoke, light beams, etc. A very
simple approach to add fog to a scene is explained in section "Fog" . This
kind of fog does not interact with any light sources though. It will not show
light beams or other effects and is therefore not very realistic.
The atmosphere effect overcomes some of the fog's limitations by calculating
the interaction between light and the particles in the atmosphere using
volume sampling. Thus shaft of light beams will become visible and objects
will cast shadows "onto" the smoke or fog.
The syntax of the atmosphere is:
atmosphere {
type TYPE
distance DISTANCE
[ scattering SCATTERING ]
[ eccentricity ECCENTRICITY ]
[ samples SAMPLES ]
[ jitter JITTER ]
[ aa_threshold AA_THRESHOLD ]
[ aa_level AA_LEVEL ]
[ color <COLOUR> ]
}
The "type" keyword determines the type of scattering model to be used. There
are five different phase functions representing the different models:
isotropic, Rayleigh, Mie (haze and murky atmosphere) and Henyey-Greenstein.
Isotropic scattering is the simplest form of scattering because it is
independent of direction. The amount of light scattered by particles in the
atmosphere does not depend on the angle between the viewing direction and the
incoming light.
Rayleigh scattering models the scattering for extremely small particles such
as molecules of the air. The amount of scattered light depends on the
incident light angle. It is largest when the incident light is parallel or
anti-parallel to the viewing direction and smallest when the incident light
is perpendicular to the viewing direction. You should note that the Rayleigh
model used here does not take the dependency of scattering on the wavelength
into account.
The Mie scattering is used for relatively small particles such as miniscule
water droplets of fog, cloud particles, and particles responsible for the
polluted sky. In this model the scattering is extremely directional in the
forward direction i.e. the amount of scattered light is largest when the
incident light is anti-parallel to the viewing direction (the light goes
directly to the viewer). It is smallest when the incident light is parallel
to the viewing direction. The haze and murky atmosphere models differ in
their scattering characteristics. The murky model is much more directional
than the haze model.
The Henyey-Greenstein scattering is based on an analytical function and can
be used to model a large variety of different scattering types. The function
models an ellipse with a given eccentricity e. This eccentricity is given by
the optional keyword "eccentricity". A value of zero defines isotropic
scattering while positive values lead to scattering in the direction of the
light and negative values lead to scattering in the opposite direction of the
light. Larger values of e (or smaller values in the negative case) increase
the directional property of the scattering.
The easiest way to use the different scattering types will be to declare some
constants and use those in your atmosphere definition:
#declare ISOTROPIC_SCATTERING = 1
#declare MIE_HAZY_SCATTERING = 2
#declare MIE_MURKY_SCATTERING = 3
#declare RAYLEIGH_SCATTERING = 4
#declare HENYEY_GREENSTEIN_SCATTERING = 5
The "distance" keyword is used to determine the density of the particles in
the atmosphere. This density is constant for the whole atmosphere. The
distance parameter works in the same way as the fog distance.
With the "scattering" keyword you can change the amount of scattering. This
is useful to fit the intensity of the scattered light to your and your
scene's needs.
Since the atmosphere is calculated by sampling along the viewing ray and
looking for contributions from light sources, it is prone to aliasing (just
like any sampling technique). There are four parameters to minimize the
artifacts that may be visible: "samples", "jitter", "aa_level", and
"aa_threshold".
The "samples" keyword determines how many samples are calculated in one
interval along the viewing ray. The length of the interval is either the
distance as given by the distance keyword or the length of the "lit" part of
the viewing ray, whichever is smaller. This lit part is a section of the ray
that is "most likely" lit by a light source. In the case of a spotlight it is
the part of the ray that lies in the cone of light. In other cases it becomes
more difficult. The only thing you should keep in mind is that the actual
sampling interval length is variable but there will never be fewer than the
specified samples in the specified distance.
One technique to reduce the visibility of sampling artifacts is to jitter the
sample points, i.e. to add random noise to their location. This can be done
with the "jitter" keyword.
Another technique is supersampling (an anti-aliasing method). This helps to
avoid missing features by adding additional samples in places were high
intensity changes occur (e.g. the edge of a shadow). The anti-aliasing is
turned on by the "aa_level" keyword. If this is larger than zero
supersampling will be used. The additional samples will be recursively placed
between two samples with a high intensity change. The level to which
subdivision takes places is specified by the "aa_level" keyword. Level one
means one subdivision (one additional sample), level two means two
subdivisions (up to three additional samples), etc.
The threshold for the intensity change is given by the "aa_threshold"
keyword. If the intensity change is greater than this threshold anti-aliasing
will be used for those two samples.
With spotlights you'll be able to create the best results because their cone
of light will become visible. Pointlights can be used to create effects like
street lights in fog. Fill-lights are not taken into account when calculating
atmospheric effects. They can be used to increase the overall light level off
the scene to make it look more realistic.
3.7.2 Background
A background color can be specified if desired. Any ray that doesn't hit an
object will be colored with this color. The default background is black. The
syntax for background is:
background { colour <COLOUR> }
3.7.3 Fog
Fog is defined by the following statement:
fog {
fog_type FOG_TYPE
distance DISTANCE
colour <COLOUR>
[ turbulence <TURBULENCE> ]
[ turb_depth TURB_DEPTH ]
[ omega OMEGA ]
[ lambda LAMBDA ]
[ octaves OCTAVES ]
[ fog_offset FOG_OFFSET ]
[ fog_alt FOG_ALT ]
}
Currently there are two fog types, constant fog and ground fog. Constant fog
has a constant density everywhere while ground fog thins out along the
y-axis. The location of the maximum density is given by the "fog_offset"
keyword and the height of the fog layer is specified by the "fog_alt"
keyword. The ground fog fades to nothing along the y-axis from fog_offset to
the distance fog_alt.
Two constants are defined for easy use of the fog types in the file
"const.inc":
// FOG TYPE CONSTANTS
#declare Constant_Fog = 1
#declare Ground_Fog = 2
The color of a pixel with an intersection depth d is calculated by
C_pixel = exp(-d/D) * C_object + (1-exp(-d/D)) * C_fog
where D is the fog distance. At depth 0 the final color is the object's
color. If the intersection depth equals the fog distance the final color
consists of 64% of the object's color and 36% of the fog's color.
The fog color that is given by the "color" keyword has three purposes. First
it defines the color to be used in blending the fog and the background.
Second it is used to specify a translucency threshold. By using a
transmittance larger than zero one can make sure that at least that amount of
light will be seen through the fog. With a transmittance of 0.3 you'll see at
least 30% of the background. Third it can be used to make a filtering fog.
With a filter value f larger than zero the amount of background light given
by f will be multiplied with the fog color. A filter value of 0.7 will lead
to a fog that filters 70% of the background light and leaves 30% unfiltered.
Fogs may be "layered". That is, you can apply as many layers of fog as you
like. Generally this is most effective if each layer is a ground fog of
different color, altitude, and with different turbulence values.
To use multiple layers of fogs, just add all of them to the scene.
You may optionally stir up the fog by adding turbulence. The turbulence
keyword may be followed by a float or vector to specify an amount of
turbulence to be used. The omega, lambda and octaves turbulence parameters
may also be specified. See "turbulence" for details on all of these
turbulence parameters.
Additionally the fog turbulence may be scaled along the direction of the
viewing ray using the turb_depth amount. Typical values are from 0.0 to 1.0
or more. The default value is 0.5 but and float value may be used.
3.7.4 Sky Sphere
The sky sphere is used create a realistic sky background without the need of
an additional sphere to simulate the sky. Its syntax is:
skysphere {
pigment { PIGMENT1 }
pigment { PIGMENT2 }
pigment { PIGMENT3 }
...
}
The sky sphere can contain several pigment layers with the last pigment being
at the bottom, i.e. it is evaluated first, and the first pigment being at the
top, i.e. it is evaluated last. If upper layers contain filtering and/or
transmitting components lower layers will be seen. If not lower layers will
be invisible.
The sky sphere is calculated by using the direction vector as the parameter
for evaluating the pigment patterns. This leads to results independent from
the view point which pretty good models a real sky where the distance to the
sky is much larger than the distances between visible objects.
If you want to add a nice color blend to your background you can easily do
this by using the following example.
sky_sphere {
pigment {
gradient y
color_map {
[ 0.5 color CornflowerBlue ]
[ 1.0 color MidnightBlue ]
}
scale 2
translate <-1, -1, -1>
}
}
This gives a soft blend from CornflowerBlue at the horizon to MidnightBlue at
the zenith. The scale and translate operations are used to map the direction
vector values, which lie in the range from <-1, -1, -1> to <1, 1, 1>, onto
the range from <0, 0, 0> to <1, 1, 1>. Thus a repetition of the color blend
is avoided for parts of the sky below the horizon.
You should note that only one sky sphere can be used in any scene. It also
won't work as you might expect if you use camera types like the orthographic
or cylindrical camera. The orthographic camera uses parallel rays and thus
you'll only see a very small part of the sky sphere (you'll get one color
skies in most cases). Reflections in curved surface will work though, e.g.
you will clearly see the sky in a mirrored ball.
3.7.5 Rainbow
The rainbow is a fog-like, circular arc that can be used to create rainbows.
The syntax is:
rainbow {
direction <DIR>
angle ANGLE
width WIDTH
distance DISTANCE
color_map { COLOUR_MAP }
[ jitter JITTER ]
[ up <UP> ]
[ arc_angle ARC_ANGLE ]
[ falloff_angle FALLOFF_ANGLE ]
}
The "direction" vector determines the direction of the (virtual) light that
is responsible for the rainbow. Ideally this is an infinitely far away light
source like the sun that emits parallel light rays. The position and size of
the rainbow are specified by the "angle" and "width" keywords. To understand
how they work you should first know how the rainbow is calculated.
For each ray the angle between the rainbow's direction vector and the ray's
direction vector is calculated. If this angle lies in the interval from
ANGLE-WITH/2 to ANGLE+WIDTH/2 the rainbow is hit by the ray. The color is
then determined by using the angle as an index into the rainbow's colormap.
After the color has been determined it will be mixed with the background
color in the same way like it is done for fogs.
Thus the angle and width parameters determine the angles under which the
rainbow will be seen. The optional "jitter" keyword can be used to add random
noise to the index. This adds some irregularity to the rainbow that makes it
look more realistic.
The "distance" keyword is the same like the one used with fogs. Since the
rainbow is a fog-like effect it's possible that the rainbow is noticeable on
objects. If this effect is not wanted it can be avoided by using a large
distance value. By default a sufficiently large value is used to make sure
that this effect is avoided.
The "color_map" keyword is used to assign a color map that will be mapped
onto the rainbow. To be able to create realistic rainbows it is important to
know that the index into the color map increases with the angle between the
ray's and rainbow's direction vector. The index is zero at the innermost
"ring" and one at the outermost "ring". The filter and transmittance values
of the colors in the color map have the same meaning as the ones used with
fogs.
The default rainbow is a 360 degree arc that looks like a circle. This is no
problem as long as you have a ground plane that hides the lower, non-visible
part of the rainbow. If this isn't the case or if you don't want the full arc
to be visible you can use the optional keywords "up", "arc_angle" and
"falloff_angle" to specify a smaller arc.
The "arc_angle" keyword determines the size of the arc in degrees (from 0 to
360 degrees). Using a value smaller than 360 degrees gives you an arc that
abruptly vanishes. Since this doesn't look nice you can use the
"falloff_angle" keyword to specify a region in which the rainbow will
smoothly blend into the background making it vanish softly. The falloff angle
has to be smaller or equal to the arc angle.
The "up" keyword determines were the "zero angle" position is. By changing
this vector you can "rotate" the rainbow about its direction. You should note
that the arc goes from -ARC_ANGLE/2 to +ARC_ANGLE/2. The soft regions go from
-ARC_ANGLE/2 to -FALLOFF_ANGLE/2 and from +FALLOFF_ANGLE/2 to +ARC_ANGLE/2.
The following example generates a 120 degrees rainbow arc that has a falloff
region of 30 degrees at both ends:
rainbow {
direction <0, 0, 1>
angle 42.5
width 5
distance 1000
jitter 0.01
color_map { Rainbow_Color_Map }
up <0, 1, 0>
arc_angle 240
falloff_angle 60
}
It is possible to use any number of rainbows and to combine them with other
atmospheric effects.
3.8 Miscellaneous Features
3.8.1 Ambient Light
Ambient light is used to simulate the effect of interdiffuse reflection that
is responsible for lighting areas that partially or completely lie in shadow.
POV-Ray provides an ambient light source to let you easily change the
brightness of the ambient lighting without changing every ambient value in
all finish statements. It also lets you create interesting effects by
changing the color of the ambient light source.
The syntax is:
ambient_light { COLOR }
3.9 Global Settings
The global_settings statement is a "catch-all" statement that gathers
together a number of global parameters. The statement may appear anywhere in
a scene as long as its not inside any other statement. You may have multiple
global_settings statements in a scene. Whatever values were specified in the
last global_settings statement override any previous settings. Regardless of
where you specify the statement, the feature applies to the entire scene.
Note some items which were language directives in previous versions of POV-
Ray have been moved inside the global_settings statement so that it is more
obvious to the user that their effect is global. The old syntax is permitted
but generates a warning.
global_settings {
adc_bailout FLOAT
ambient_light COLOR
assumed_gamma FLOAT
hf_gray_16 BOOLEAN
irid_wavelength COLOR
max_intersections INTEGER
max_trace_level INTEGER
number_of_waves INTEGER
radiosity { RADIOSITY_ITEMS... }
}
Each item is optional and may appear in and order. If an item is specified
more than once, the last setting overrides previous values. Details on each
item is given in the following sections.
3.9.1 ADC_Bailout
In scenes with many reflective and transparent surfaces, POV-Ray can get
bogged down tracing multiple reflections and refractions that contribute very
little to the color of a particular pixel. The program uses a system called
Adaptive Depth Control (ADC) to stop computing additional reflected or
refracted rays when their contribution is insignificant.
You may use the global setting adc_bailout keyword followed by float value to
specify the point at which a ray's contribution is considered insignificant.
global_setting { adc_bailout FLOAT }
The default value is 1/255, or approximately 0.0039, since a change smaller
than that could not be visible in a 24 bit image. Generally this setting is
perfectly adequate, and should be left alone. Setting adc_bailout to 0 will
disable ADC, relying completely on max_trace_level to set an upper limit on
the number of rays spawned.
3.9.2 Ambient Light
Ambient light is used to simulate the effect of interdiffuse reflection that
is responsible for lighting areas that partially or completely lie in shadow.
POV-Ray provides an ambient light source to let you easily change the
brightness of the ambient lighting without changing every ambient value in
all finish statements. It also lets you create interesting effects by
changing the color of the ambient light source.
The syntax is:
global_setting { ambient_light COLOR }
The default is a white ambient light source set at rgb<1,1,1>. The actual
ambient used is:
AMBIENT = FINISH_AMBIENT * GLOBAL_AMBIENT
3.9.3 Assumed_Gamma
Many people may have noticed at one time or another that some images are too
bright or dim when displayed on their system. As a rule, Macintosh users find
that images created on a PC are too bright, while PC users find that images
created on a Macintosh are too dim.
The assumed_gamma global setting works in conjunction with the Display_Gamma
INI setting (see section "Display Hardware Settings" ) to ensure that scene
files render the same way across the wide variety of hardware platforms that
POV-Ray is used on. The assumed_gamma setting is used in a scene file as
follows:
global_setting { assumed_gamma FLOAT }
where the assumed_gamma is the correction factor to be applied before the
pixels are displayed and/or saved to disk. For scenes created in older
versions of POV-Ray, the assumed_gamma will be the same as the Display_Gamma
of the system the scene was created on. For PC systems, the most common
Display_Gamma is 2.2, while for scenes created on Macintosh systems should
use a scene gamma of 1.8. Another gamma value that sometimes occurs in scenes
is 1.0.
Scenes that do not have an assumed_gamma global setting will not have any
gamma correction performed on them, for compatibility reasons. If you are
creating new scenes or rendering old scenes, it is strongly recommended that
you put in an appropriate assumed_gamma global setting. For new scenes, you
should use an assumed_gamma value of 1.0 as this models how light appears in
the real world more realistically.
The following sections explain more thoroughly what gamma is and why it is
important.
3.9.3.1 Monitor Gamma
The differences in how images are displayed is a result of how a computer
actually takes an image and displays it on the monitor. In the process of
rendering an image and displaying it on the screen, several gamma values are
important, including the POV scene file or image file gamma, and the monitor
gamma.
Most image files generated by POV-Ray store numbers in the range 0 to 255 for
each of the red, green, and blue components of a pixel. These numbers
represent the intensity of each color component, with 0 being black, and 255
being the brightest color (either 100% red, 100% green, or 100% blue). When
an image is displayed, the graphics card converts each color component into a
voltage which is sent to the monitor to light up the red, green, and blue
phosphors on the screen. The voltage is usually proportional to the value of
each color component.
Gamma becomes important when displaying intensities that aren't the maximum
or minimum possible values. For example, 127 should represent 50% of the
maximum intensity for pixels stored as numbers between 0 and 255. On systems
that don't do gamma correction, 127 will be converted to 50% of the maximum
voltage, but because of the way the phosphors and the electron guns in a
monitor work, this may be only 22% of the maximum color intensity on a
monitor with a gamma of 2.2. To display a pixel which is 50% of the maximum
intensity on this monitor, we would need a voltage of 73% of the maximum
voltage, which translates to storing a pixel value of 186.
The relationship between the input pixel value and the displayed intensity
can be approximated by an exponential function (^ means exponentiation):
obright = ibright ^ display_gamma
where obright is the output intensity, and ibright is the input pixel
intensity. Both values are in the range 0 to 1 (0% to 100%). Most monitors
have a fixed gamma value in the range 1.8 to 2.6. Using the above formula
with display_gamma values greater than 1.0 means the output brightness will
be less than the input brightness. In order to have the output and input
brightness be equal, an overall system gamma of 1.0 is needed. To do this, we
need to gamma correct the input brightness in the same manner as above, but
with a gamma value of 1.0/ display_gamma before it is sent to the monitor. To
correct for a display gamma of 2.2, this pre-monitor gamma correction uses a
gamma value of 1.0/2.2, or approximately 0.45.
How the pre-monitor gamma correction is done depends on what hardware and
software is being used. On Macintosh systems, the operating system has taken
it upon itself to insulate applications from the differences in display
hardware. Through a gamma control panel, the user may be able to set the
actual monitor gamma, and MacOS will then convert all pixel intensities so
that the monitor will appear to have the specified gamma value. On Silicon
Graphics machines, the display adapter has built-in gamma correction
calibrated to the monitor which gives the desired overall gamma (the default
is 1.7). Unfortunately, on PCs and most UNIX systems, it is up to the
application to do any gamma correction needed.
3.9.3.2 Image File Gamma
Since most PC and UNIX applications and image file formats don't understand
display gamma, they don't do anything to correct for it. As a result, users
creating images on these systems adjust the image in such a way that it has
the correct brightness when displayed. This means that the data values stored
in the files are made brighter to compensate for the darkening effect of the
monitor. In essence, the 0.45 gamma correction is built in to the image files
created and stored on these systems. When these files are displayed on a
Macintosh system, the gamma correction built in to the file, in addition to
gamma correction built into MacOS means that the image will be too bright.
Similarly, files that look correct on Macintosh or SGI systems because of the
built-in gamma correction will be too dark when displayed on a PC.
The new PNG format files generated by POV 3.0 overcome the problem of too
much or not enough gamma correction by storing the image file gamma (which is
1.0/ Display_Gamma) inside the PNG file when it is generated by POV-Ray. When
the PNG file is later displayed by a program that has been set up correctly,
it uses this gamma value as well as the current display gamma to correct for
the potentially different display gamma used when originally creating the
image.
Unfortunately, of all the image file formats POV supports, PNG is the only
one that has any gamma correction features and is therefore preferred for
images that will be displayed on a wide variety of platforms.
3.9.3.3 Scene File Gamma
The image file gamma problem itself is just a result of how scenes themselves
are generated in POV-Ray. When you start out with a new scene and are placing
light sources, and adjusting surface textures and colors, you generally make
several attempts before the lighting is how you like it. How you choose these
settings depends upon the preview image, or the image file stored to disk,
which in turn is dependent upon the overall gamma of the display hardware
being used.
This means that as the artist, you are doing gamma correction in the POV-Ray
scene file for your particular hardware. This scene file will generate an
image file that is also gamma corrected for your hardware, and will display
correctly on systems similar to your own. However, when this scene is
rendered on another platform, it may be too bright or too dim, regardless of
the output file format used. Rather than have you change all the scene files
to have a single fixed gamma value (heaven forbid!), POV-Ray 3.0 allows you
to specify in the scene file the Display_Gamma of the system that the scene
was created on.
The assumed_gamma global setting, in conjunction with the Display_Gamma INI
setting lets POV-Ray know how to do gamma correction on a given scene so that
the preview and output image files will appear the correct brightness on any
system. Since the gamma correction is done internally to POV-Ray, it will
produce output image files that are the correct brightness for the current
display, regardless of what output format is used. As well, since the gamma
correction is performed in the high-precision data format the POV-Ray uses
internally, it produces better results than gamma correction done after the
file is written to disk.
Although you may not notice any difference in the output on your system with
and without an assumed_gamma setting, the {HIW/}assumed_gamma is important if
the scene is ever rendered on another platform.
3.9.4 HF_Gray_16
The hf_gray_16 setting is useful when using POV-Ray to generate heightfields
for use in other POV-Ray scenes. The syntax is...
global_setting { hf_gray_16 BOOLEAN }
The boolean values turns the option on or off. If the keyword is specified
without the boolean value then the option is turned on. If hf_gray_16 is not
specified in any global_settings statement in the entire scene then the
default is off.
When hf_gray_16 is on, the output file will be in the form of a heightfield,
with the height at any point being dependent on the brightness of the pixel.
The brightness of a pixel is calculated in the same way that color images are
converted to grayscale images, as follows:
height = 0.3 * red + 0.59 * green + 0.11 * blue
Setting the hf_gray_16 option will cause the preview display, if used, to be
in a grayscale rather than color. This is to allow you to see how the
heightfield will look, because some file formats store heightfields in a way
that is difficult to understand afterwards. See section "Height Field" for a
description of how POV-Ray heightfields are stored for each file type.
3.9.5 Irid_Wavelength
Iridescence calculations depend upon the dominant wavelengths of the primary
colors of red, green and blue light. You may adjust the values using the
global setting irid_wavelength as follows...
global_settings { irid_wavelength COLOR }
The default value is rgb<0.25,0.18,0.14> and any filter or transmit values
are ignored. These values are proportional to the wavelength of light but
they represent no real world units.
In general, the default values should prove adequate, but we provide this
option as a means to experiment with other values.
3.9.6 Max_Trace_Level
In scenes with many reflective and transparent surfaces, POV-Ray can get
bogged down tracing multiple reflections and refractions that contribute very
little to the color of a particular pixel. The global setting max_trace_level
defines the maximum number of recursive levels that POV-Ray will trace a ray.
global_settings { max_trace_level INTEGER }
This is used when a ray is reflected or is passing through a transparent
object and when shadow rays are cast. When a ray hits a reflective surface,
it spawns another ray to see what that point reflects, that's trace level 1.
If it hits another reflective surface, then another ray is spawned and it
goes to trace level 2. The maximum level by default is 5.
One speed enhancement added to POV-Ray in version 3.0 was Adaptive Depth
Control , or ADC. Each time a new ray is spawned as a result of reflection or
refraction, its contribution to the overall color of the pixel is reduced by
the amount of reflection or the filter value of the refractive surface. At
some point, this contribution can be considered to be insignificant, and
there is no point in tracing any more rays. Adaptive depth control is what
tracks this contribution and makes the decision of when to bail out. On
scenes that use a lot of partially reflective or refractive surfaces, this
can result in a considerable reduction in the number of rays fired and makes
it "safer" to use much higher max_trace_level values.
This reduction in color contribution is a result of scaling by the reflection
amount and/or the filter values of each surface, so a perfect mirror or
perfectly clear surface will not be optimizable by ADC. You can see the
results of ADC by watching the "Rays Saved" and "Highest Trace Level"
displays on the statistics screen.
The point at which a ray's contribution is considered insignificant is
controlled by the adc_bailout value. The default adc_bailout is 1/255, or
approximately 0.0039, since a change smaller than that could not be visible
in a 24 bit image. Generally this setting is perfectly adequate, and should
be left alone. Setting adc_bailout to 0 will disable ADC, relying completely
on max_trace_level to set an upper limit on the number of rays spawned.
If max trace level is reached before a non-reflecting surface is found, and
if ADC hasn't allowed an early exit from the ray tree, then the color is
returned as black. Raise max_trace_level if you see black in a reflective
surface where there should be a color.
The other symptom you could see is with transparent objects. For instance,
try making a union of concentric spheres with a clear texture on them. Make
ten of them in the union with radius's from 1-10 then render the Scene. The
image will show the first few spheres correctly, then black. This is because
a new level is used every time you pass through a transparent surface. Raise
max_trace_level to fix this problem. For example:
Note: Raising max_trace_level will use more memory and time and it could
cause the program to crash with a stack overflow error, although ADC will
alleviate this to a large extent. Values for max_trace_level are not
restricted, so it can be set to any number as long as you have the time and
memory. However, increasing its setting does not necessarily equate to
increased image quality unless such depths are really needed by the scene.
3.9.7 Max_Intersections
POV-Ray uses a set of internal stacks to collect ray/object intersection
points. The usual maximum number of entries in these "I-Stacks" is 64.
Complex scenes may cause these stacks to overflow. POV-Ray doesn't stop but
it may incorrectly render your scene. When POV-Ray finishes rendering, a
number of statistics are displayed. If you see "I-Stack Overflows" reported
in the statistics, you should increase the stack size. Add a global setting
to your scene as follows:
global_settings { max_intersections INTEGER }
3.9.8 Number_Of_Waves
The wave and ripples pattern are generated by summing a series of waves, each
with a slightly different center and size. By default, ten waves are summed,
but this amount can be globally controlled by changing the number_of_waves
setting.
global_settings { number_of_waves INTEGER }
Changing this value affects both waves and ripples alike on all patterns in
the scene.
3.9.9 Radiosity
Radiosity is an extra calculation that more realistically computes the
diffuse interreflection of light. This diffuse reflection can be seen if you
place a white chair in a room full of blue carpet, blue walls, and blue
curtains, the chair will pick up a blue tint from light reflecting off of
other parts of the room. Also notice that the shadowed areas of your
surroundings are not totally dark even if no light source shines directly on
the surface. Diffuse light reflecting off of other objects fills in the
shadows. Typically ray tracing uses a trick called "ambient" light to
simulate such effects but it is not very accurate.
Radiosity is more accurate than simplistic ambient light but it takes much
longer to compute. For this reason, POV-Ray does not use radiosity by
default. Radiosity is turned on using Quality=10 or Quality=11 options in an
INI file or +q10 or +q11 command line switch. The default quality is 9 and
uses no radiosity. A value of 10 uses radiosity but does not compute halos.
Quality 11 uses radiosity and halos. See "Quality Settings" for details.
The following sections describes how radiosity works, how to control it with
various global settings and tips on trading quality vs. speed.
3.9.9.1 How Radiosity Works
The problem of ray tracing is to figure out what the light level is at each
point that you can see in a scene. Traditionally, in ray tracing, this is
broken into the sum of these components:
- Diffuse, the effect that makes the side of things facing the light
brighter;
- Specular, the effect that makes shiny things have dings or sparkles on
them;
- Reflection, the effect that mirrors give; and
- Ambient, the general all-over light level that any scene has, which keeps
things in shadow from being pure black.
POV's radiosity system, based on a method by Greg Ward, provides a way to
replace the last term - the constant ambient light value - with a light level
which is based on what surfaces are nearby, and how bright in turn they are.
The first thing you might notice about this definition is that it is
circular: the light of everything is dependent on everything else, and vice
versa. This is true in real life, but in the world of ray tracing, we can
make an approximation. The approximation that is used is: the objects you are
looking at have their 'ambient' values calculated for you, by checking the
other objects nearby. When those objects are checked during this process,
however, a traditional constant ambient term is used.
How does POV calculate the ambient term for each point? By sending out more
rays, in many different directions, and averaging the results. A typical
point might use 200 or more rays to calculate its ambient light level
correctly.
Now, this sounds like it would make the ray tracer 200 times slower. This is
true, except that the software takes advantage of the fact that ambient light
levels change quite slowly. (Remember, shadows are calculated separately, so
sharp shadow edges are not a problem). Therefore, these extra rays are sent
out only "once in a while" (about 1 time in 50), then these calculated values
are saved and reused for nearby pixels in the image when possible.
This process of saving and reusing values is what causes the need for a
variety of tuning parameters, so you can get the scene to look just the way
you want.
3.9.9.2 Adjusting Radiosity
As described earlier, radiosity is turned on by using a quality level of 10
or 11, however radiosity has many parameters that are specified in a
radiosity {...} statement inside a global_settings {...} statement as
follows:
global_settings {
radiosity {
brightness FLOAT
count INTEGER
distance_maximum FLOAT
error_bound FLOAT
gray_threshold FLOAT
low_error_factor FLOAT
minimum_reuse FLOAT
nearest_count INTEGER
recursion_limit INTEGER
}
}
Each item is optional and may appear in and order. If an item is specified
more than once, the last setting overrides previous values. Details on each
item is given in the following sections.
3.9.9.2.1 brightness
This is the degree to which ambient values are brightened before being
returned upwards to the rest of the system. If an object is red <1, 0, 0>,
with an ambient value of 0.3, then in normal situations a red component of
0.3 will be added in. With radiosity on, assume it was surrounded by an
object of color grey60 <0.6, 0.6, 0.6>. The average color returned by the
gathering process will be the same. This will be multiplied by the texture's
ambient weight value of 0.3, returning <0.18, 0.18, 0.18>. This is much
darker than the 0.3 which would be added in normally. Therefore, all returned
values are brightened by the inverse of the average of the calculated values,
so the average ambient added in does not change. Some will be higher than
specified (higher than 0.3 in this example), and some will be lower, but the
overall scene brightness will be unchanged.
3.9.9.2.2 count
The number of rays that are sent out whenever a new radiosity value has to be
calculated. Values of 100-150 make most scenes look good. Higher values might
be needed for scenes with high contrast between light levels, or small
patches of light causing the illumination. This would be used only for a
final rendering on an image, since it is very compute intensive. Since most
scenes calculate the ambient value at 1% to 2% of pixels, as a rough
estimate, your rendering will take 1% to 2% of this number times as long. If
you set it to 300, your rendering might take 3 to 6 times as long to complete
(1% to 2% times 300).
When this value is too low, the light level will tend to look a little bit
blotchy, as if the surfaces you're looking at were slightly warped. If this
is not important to your scene (as in the case that you have a bump map, or
if you have a strong texture), then by all means use a lower number.
3.9.9.2.3 distance_maximum
This is the only tuning value that depends upon the size of the objects in
the scene. This one must be set for scenes to render properly... the rest can
be ignored for a first try. It is difficult to describe the meaning simply,
but it sets the distance in model units from a sample at which the error is
guaranteed to hit 100% (Radiosity_Error_Bound >= 1): no samples are reused at
a distance larger than this from their original calculation point.
So, imagine an apple at the left edge of a table. The goal is to make sure
that samples on the surface of the table at the right are not used too close
to the apple, and definitely not underneath the apple. If you had enough
rays, there wouldn't be a problem, since one of them would be guaranteed to
hit the apple and set the reuse radius properly for you. In practice, you
must limit this.
I use this technique: which object in your scene might have this problem: (a
small object on a larger flatter surface, that you want good ambient light
near). Now, how far from this would you have to get to be sure that one of
your rays had a good chance of hitting it? In the apple-on-the-table example,
assuming I used one POV-Ray unit as one inch, I might use 30 inches. A
theoretically sound way (when you are running lots of rays) is the distance
at which this object's top is 5 degrees above the horizon of the sample point
you are considering. This corresponds to about 11 times the height of the
object. So, for a 3-inch apple, 33 inches makes some sense. For good behavior
under and around a 1/3 inch pea, use 3 inches etc. Another VERY rough
estimate is one third the distance from your eye position to the point you
are looking at. The reasoning is that you are probably no more than 90 inches
from the apple on the table, if you care about the shading underneath it.
3.9.9.2.4 error_bound
This is one of the two main speed/quality tuning values (the other is of
course the number of rays shot). In an ideal world, this would be the only
{END/} value needed. It is intended to mean the fraction of error tolerated.
For example, if it were set to 1, then the algorithm would not calculate a
new value until the error on the last one was estimated at as high as 100%.
Ignoring the error introduced by rotation for the moment, on flat surfaces
this is equal to the fraction of the reuse distance, which in turn is the
distance to the closest item hit. So, if you have an old sample on the floor
10 inches from a wall, an error bound of .5 will get you a new sample at a
distance of about 5 inches from the wall. .5 is a little rough and ready, .33
is good for final renderings. Values much lower than .3 take forever.
The default value is 0.4.
3.9.9.2.5 gray_threshold
Diffusely interreflected light is a function of the objects around the point
in question. Since this is recursively defined to millions of levels of
recursion, in any real life scene, every point is illuminated at least in
part by every other part of the scene. Since we can't afford to compute this,
we only do one bounce, and so the calculated ambient light is very strongly
affected by the colors of the objects near it. This is known as color bleed,
and it really happens, but not as much as this calculation method would have
you believe. So, this variable grays it down a little, to make your scene
more believable. A value of .6 means to calculate the ambient value as 60% of
the equivalent grey value calculated, plus 40% of the actual value
calculated. At 0%, this feature does nothing. At 100%, you always get
white/grey ambient light, with no hue. Note that this does not change the
lightness/darkness, only the strength of hue/grayness. (In HLS terms, it
changes H only).
3.9.9.2.6 low_error_factor
If you calculate just enough samples, but no more, you will get an image
which has slightly blotchy lighting. What you want is just a few extra
interspersed, so that the blending will be nice and smooth. The solution to
this is the mosaic preview: it goes over the image one or more times
beforehand, calculating radiosity values. To ensure that you get a few extra,
the radiosity algorithm lowers the error bound during the pre-final passes,
the sets it back just before the final pass. This tuning value sets the
amount that the error bound is dropped during the preliminary image passes.
So, if your low error factor is .8, and your error bound is set to .4, then
it will really use an error bound of .32 during the first passes and .4 on
the final pass.
3.9.9.2.7 minimum_reuse
The minimum effective radius ratio. This is the fraction of the screen width
which sets the minimum radius of reuse for each sample point. (Actually, it
is the fraction of the distance from the eye, but the two are roughly equal).
For example, if the value is .02, then the radius of maximum reuse for every
sample is set to whatever ground distance corresponds to 2% of the width of
the screen. Imagine you sent a ray off to the horizon, and it hit the ground
at a distance of 100 miles from your eyepoint. The reuse distance for that
sample will be set to 2 miles. At a resolution of 300 x 400, this will
correspond to (very roughly) 8 pixels. The theory is that you don't want to
calculate values for every pixel into every crevice everywhere in the scene,
it will take too long. This sets a minimum bound for the reuse. If this value
is too low, (which is should be in theory) rendering gets slow, and inside
corners can get a little grainy. If it is set too high, you don't get the
natural darkening of illumination near inside edges, since it reuses. At
values higher than 2% you start getting more just plain errors, like reusing
the illumination of the open table underneath the apple.
Remember! This is a unitless ratio.
3.9.9.2.8 nearest_count
This is the maximum number of old ambient values blended together to create a
new interpolated value. It will always be the N geometrically closest
reusable points that get used. If you go lower than 4, things can get pretty
patchy. This can be good for debugging, though. Must be no more than 10,
since that is the size of the array allocated.
3.9.9.2.9 radiosity_quality
3.9.9.2.10 recursion_limit
This value determines how many recursion levels are used to calculate the
diffuse inter-reflection. Valid values are one and two.
3.9.9.3 Tips on Radiosity
If you want to see where your values are being calculated, set the
Radiosity_Count down to about 20, set the Radiosity_Nearest_Count to 1, and
set the Radiosity_Grey to 0. This will make everything maximally patchy, so
you'll be able to see the borders between patches. There will have been a
radiosity calculation at the center of most patches. As a bonus, this is
quick to run. You can then change the Radiosity_Error_Bound up and down, and
see how it changes things. Likewise the Radiosity_Reuse_Dist_Min and Max.
One way to get extra smooth results: crank up the sample count (I've done as
high as 1300) , and drop the low_error_factor to something small like .6.
Bump up the reuse_count to 7 or 8. This will get better values, and more of
them, then interpolate among more of them on the last pass. This is not for
people with a lack of patience, since it is like a squared function. If your
blotchiness is only in certain corners or near certain objects, try tuning
the error bound instead. Never drop it by more than a little at a time, since
the run time will get very long.
If your scene looks good, but right near some objects you get spots of the
right (usually darker) color showing on a flat surface of the wrong color
(same as far away from the object), then try dropping the reuse_dist_max. If
that still doesn't work well, then increase your ray count by 100 and drop
the error bound just a bit. If you still have problems, drop the
reuse_nearest_count to about 4.
APPENDIX A POV-Ray Output Messages
APPENDIX A.1 Options in Use
APPENDIX A.2 Warning Messages
APPENDIX A.2.1 Warnings during the Parsing Stage
APPENDIX A.2.2 Other Warnings
APPENDIX A.3 Error Messages
APPENDIX A.3.1 Scene File Errors
APPENDIX A.3.2 Other Errors
APPENDIX A.4 Statistics
APPENDIX B Help on Help
Using the Help Reader (POVHELP.EXE)
KNOWN INCOMPATIBILITIES
See after the Quick Intro.
Quick Intro
Use the +E option to make the help reader a pop-up program.
Use Space to go to the next section.
Use Ctrl-PgUp and Ctrl-PgDn to move between sections also.
Use Tab to highlight hypertext links.
Use Alt-Tab to highlight code fragments.
Use Enter to jump to a highlighted hypertext link.
Use +/- to jump to relevant sections once link jumping has started.
Use BACKSPACE to return to the last place you were before a search/jump.
Use 'S' to search on a keyword.
Use 'J' to toggle text justification when reading a section.
Use 'P' to paste code into your application via the keyboard buffer.
POV-Help will handle non-standard page widths provided the BIOS column count
is correctly updated by whatever program is being used to alter it from 80
columns.
If you use POV-Help as a pop-up program, it will attempt to search on the
word under your cursor when you pop it up. Note that if you exit pop-up mode
by using the hot-key, POV-Help takes this to mean that you want to return to
the same place next time and will not perform a search. A search is only
performed if you exited using ESCAPE (meaning you have finished with the
current subject.)
The history stack activated by using Backspace holds 32 entries.
KNOWN INCOMPATIBILITIES
POV-Help does not work with MS-DOS's EDIT program. [In fact, EDIT.COM is
really QBASIC.EXE with a few add ons ; EDIT needs QBASIC to run.]
If it won't work with your editor, try this (assuming you have macro
facilities) -
o write a macro to get the word under the cursor
o have it call POVHELP.EXE with the word as a parameter
o bind the macro to your key-sequence of choice.
Co+Iname ine (case insensuse alternate file name (default HELP.PHE)
+N123 go to the 123rd section (NOT section 123!)
+S4.5.6 go to section '4.5.6'
+Tsphere or "+Tsphere" go straight to the first section found with 'sphere'
in its title.
+W50 window width 40 characters (max 127)
+H15 window height 15 lines (max 21)
+J[-] justify ON (default), -J- to turn off
+PH[n] send 'n' HOME keys after each CR when pasting.
default is -ph1.
+KALT-ESC hot key sequence. can be CTRL|ALT|CTRL-ALT+[Any
character]|[ESC]. e.g. +KCTRL-ALT-P, +KCTRL-1,
+KALT-CTL-'. CTL is also acceptable.
+Eabc d e run program 'abc' with parameters 'd' and 'e'. all
parameters after the '+e' are passed to the program.
text same as +T unless collecting +E parameters, where it
is a parameter
ViUp, Down move highlight bar
Enter view selected item
Escape exit help viewer
AuUp, Down pyrscroll screen
PgUp, PgDn scroll screen
Left, Right scroll screen
Escape return to top menu
SeUp, Down scroll screen
PgUp, PgDn scroll screen
Left, Right scroll screen
Escape return to top menu
Space or CtrlPgDn view next section
CtrlPgUp view previous section
"+", Enter jump to first/next hypertext link
"-" jump to previous link/original section
"B" jump back to original section (from before link jumping)
Tab select next visible link, wraps from last to first
ShiftTab select previous visible hypertext link
AltTab select code fragment for pasting.
"P" paste highlighted code fragment via keyboard buffer.
General
The help reader wraps most text. Excluded are specified portions, lists, and
a few others. Use the left and right arrow keys to scroll these if need be.
The help reader is intended to be a 'shell' around an editor program. Some
people may prefer the term 'shim'.
Using EMS for most memory requirements, it loads itself and then runs your
editor for you, providing pop-up help facilities. It will also be able to
paste code fragments into your source. If your editor was, for example, 'ME',
you would place a batch file called 'ME.BAT' in your scene development
directory. If you use 'VI', you'd create 'VI.BAT', and so on.
(YOUR-EDITOR-NAME.BAT)
desired key sequence ───┐
│
┌─────────┐ ┌───┴────────┐ ┌──────────────┐
povhelp │+W50 +H15│ │+KCTRL-ALT-H│ │+Ed:\me\me.exe│ %1 %2 %3 %4 %5
└───────┬─┘ └────────────┘ └───┬──────────┘
│ │
size of window ─┘ │
│
place path to your editor here ────────┘
For example -
povhelp +W50 +H15 +KALT-H +Ed:\me\me.exe %1 %2 %3 %4 %5
This
command line will yield a version of POV-Help with a 50x15 window, popped-up
with the ALT-H key sequence, over the editor 'd:\me\me.exe'. If you don't
specify a key sequence, POV-Help defaults to using ALT-ESC.
This would load the help reader. which would then load ME.EXE, and things
would proceed as normal. When you exit your editor, the help reader
automatically unloads. You can use the ALT-ESC key sequence to pop up
POVHELP. This is the default ; there is a way to set it. Note that no other
parameters may appear after the +E parameter as they will just be passed to
the program being run.
If you use the hotkey to pop-up, POVHELP performs a simplistic search of
sections and titles based on the word under the cursor. If found, you are
taken to that. Otherwise, you are taken to the main menu, unless you
hot-keyed out.
You can hot-key out of the actual section text, by using the same hot key
that got you in. If you press escape, you are taken back up to the top menu.
But if you hotkey out, you go back to your program. Next time you press the
hot key, you will be taken back to the same place. No search is performed in
this case.
POVHELP needs EMS if it is running as a shell program.
If you don't specify the +E parameter, POVHELP will come up as a stand-alone
program, in which case it does not use EMS.
If you highlight a section of code using Alt-Tab, and you are using POV-Help
in pop-up mode, then you may paste the code via the keyboard buffer using
'P'.
As many editors today use auto-indentation, this may cause some problems with
column alignment. For that reason, POV-Help by default inserts a HOME key
code into the keyboard buffer after each CR. Some editors require more than
one HOME key operation to get to the left column. For this reason, the number
of HOME's sent may be adjusted from 0 (none) to 9 using the +PH[n]
command-line parameter. 'n' is any value from 0 to 9 and defaults to 1.
POV-Help was written by Christopher J. Cason.
CIS : 100032,1644.
Internet : cjcason@yarrow.wt.uwa.edu.au.
Converters will be available which translate POV-Help databases to other
formats such as Postscript, LaTeX, RTF, Windows Help, HTML, etc.
The format of the POV-Help database is documented and freely available.
POV-Help is free. It may not be sold. See POVLEGAL.DOC for details. The
POV-Help suite of programs is copyright (c) 1994 C.J. Cason and the POV-Team.
APPENDIX C Frequently Asked Questions
Q. When will POV-Ray 3.0 be released?
A. In beta form... Now!
Q. When will the source code be released?
A. When all platforms finish beta testing.
Q. When will other platforms go beta?
APPENDIX D Where to Get More POV-Ray Stuff
Persistence of Vision(tm) Ray Tracer
POV-Ray(tm) Version 3.0
Where to Get It and Other Info
Draft: February 8, 1996
The Persistence of Vision(tm) Ray Tracer creates three-dimensional,
photo-realistic images using a rendering technique called ray tracing. It
reads in a text file containing information describing the objects and
lighting in a scene and generates an image of that scene from the view
point of a camera also described in the text file. Ray tracing is not a
fast process by any means, but it produces very high quality images with
realistic reflections, shading, perspective, and other effects.
The POV-Ray(tm) package includes detailed instructions on using the
ray tracer and creating scenes. Many stunning scenes are included with POV-
Ray so you can start creating images immediately when you get the package.
These scenes can be modified by the user also so they don't have to start
from scratch.
In addition to the pre-defined scenes are a large library of
predefined shapes and materials that can be used in your own scenes by just
typing the name of the shape or material.
POV-Ray is easy to use, and also includes many advanced features like
bezier patches, blobs, height-fields, bump mapping, and material mapping.
POV-Ray can be used under MS-Dos, Windows 3,x, NT & '95; Apple
Macintosh 68k and Power PC; Commodore Amiga; Linux, UNIX, and other
computers.
Here is a list the files that you need to use POV-Ray on your
computer.
The latest versions of these files are available over CompuServe,
Internet, America Online, and several BBS's. See 'Where to find POV-Ray
files' section below for more info.
----------------------------------------------------------------------------
For MS-Dos systems:
-------------------
The MS-Dos version runs under Ms-Dos, or as a dos application under
Windows'95, Windows NT, Windows 3.1 or 3.11. It also runs
under OS/2 and Warp.
Required hardware & software:
- A 386 or better CPU and at least 4 meg of RAM.
- About 6 meg disk space to install and 2-10 meg or more beyond
that for working space.
- A text editor capable of editing plain ASCII text files.
The EDIT program that comes with MS-Dos will work for moderate
size files.
- Graphic file viewer capable of viewing GIF and perhaps TGA
and PNG formats.
Required POV-Ray files:
- POVMSDOS.EXE -- a self-extracting archive containing
the program, sample scenes, standard include files, and
documentation in a hypertext help format with help viewer.
Recommended:
- Pentium or 486dx or math co-processor for 386 or 486sx
- 8 meg or more RAM.
- SVGA display preferably with VESA interface and high color
or true color ability.
Optional:
The source code is not needed to use POV-Ray. It is provided
for the curious and adventurous.
- POVMSD_S.ZIP - The C source code for POV-Ray for MS-Dos.
Contains generic parts and MS-Dos specific parts. Includes
sample scenes, standard include files, and documentation in
a hypertext help format with help viewer.
- A C compiler that can create 32-bit protected mode applications.
We support Watcom 10.5a, Borland 4.52 with Dos Power Pack and
limited graphics under DJGPP 1.12maint4. DJGPP 2.0 not supported.
For Windows systems:
--------------------
The Windows version runs under Windows'95, Windows NT, and under
Windows 3.1 or 3.11 if Win32s extensions are added.
Required hardware & software:
- A 386 or better CPU and at least 8 meg of RAM.
- About 6 meg disk space to install and 2-10 meg or more beyond
that for working space.
- A text editor capable of editing plain ASCII text files.
The Windows notepad program that comes with Windows will work
for moderate size files.
Required POV-Ray files:
- User archive POVWIN32.EXE -- a self-extracting archive containing
the program, sample scenes, standard include file, and
documentation.
Recommended:
- Pentium or 486dx or math co-processor for 386 or 486sx
- 16 meg or more RAM.
- SVGA display preferably with high color or true color ability
and drivers installed.
Optional:
The source code is not needed to use POV-Ray. It is provided
for the curious and adventurous.
- POVWIN_S.ZIP - The C source code for POV-Ray for Windows.
Contains generic parts and Windows specific parts,
includes sample scenes, standard include files, and
documentation.
- POV-Ray can only be compiled using C compilers that create
32-bit Windows applications. We support Watcom 10.5a,
Borland 4.52 compilers.
For Macintosh systems:
----------------------
The Macintosh versions run under Apple's MacOS operating system
version 7.0 or better, on 68K-based Macintosh or Power Macintosh
computers.
Required hardware & software:
- A 68020 (Mac II) or better CPU with floating point unit or
software fpu emulator (e.g. SoftwareFPU) and at least
8 MB RAM
*or*
- Any Power Macintosh computer and at least 8 MB RAM
- System 7 or newer and color QuickDraw, System 6 is no longer
supported.
- About 6 MB free disk space to install and an additional
2-10 MB free space for working space.
- Graphic file viewer capable of viewing Mac PICT, GIF,
and perhaps TGA and PNG formats (shareware GIFConverter
or GraphicConverter are good.)
Required POV-Ray files:
- POVMAC68.SIT -- a Stuffit archive containing the 68K Macintosh
program, sample scenes, standard include files, and documentation.
*or*
- POVPMAC.SIT -- a Stuffit archive containing the native Power
Macintosh program, sample scenes, standard include files, and
documentation.
Recommended:
- 68030/33 or faster, or any Power Macintosh
- 68K Macintosh: 8 MB or more RAM;
Power Macintosh systems: 16 MB or more.
- Color monitor preferred, 256 colors OK, but thousands
or millions of colors even better.
Optional:
The source code is not needed to use POV-Ray. It is provided
for the curious and adventurous. POV-Ray can be compiled
using Apple's MPW 3.3, Metrowerks CodeWarrior 8, or Symantec 8.
POVMACS.ZIP - The C source code for POV-Ray for Macintosh.
Contains generic parts and Macintosh specific parts. Includes
sample scenes, standard include files, and documentation.
For Amiga systems:
------------------
The Amiga version comes in several flavors, 68000/68020 without
FPU, (not recommended, very slow) 68020/68881(68882), 68030/68882
and 68040. There are also two sub-versions, one with a CLI-only
interface, and one with a GUI (requires MUI 3.1). All versions
run under OS2.1 and up. Support exists for pensharing and window
display under OS3.x with 256 color palettes, and CybeGFX display
library support.
Required:
- at least 4 meg of RAM.
- at least 2 meg of hard disk space for the necessities, 5-20 more
recommended for workspace.
- an ASCII text editor, GUI configurable to launch the editor of
your choice.
- Graphic file viewer - POV-Ray outputs to PNG, Targa (TGA), and
PPM formats, converters from the PPMBIN distribution are
included to convert these to IFF ILBM files.
Recommended:
- 8 meg or more of RAM.
- 68030 & 68882 or higher processor.
- 24bit display card (CyberGFX library supported)
As soon as a stable compiler is released for Amiga PowerPC
systems, plans are to add this to the flavor list.
For Linux on Intel 80x86 CPU:
-----------------------------
Required hardware & software:
- A 386 or better CPU and at least 4 meg of RAM.
- About 6 meg disk space to install and 2-10 meg or more beyond
that for working space.
- A text editor capable of editing plain ASCII text files.
- Any recent (1994 onwards) Linux kernel and support for the
lib.so-style loading. POV-Ray for Linux is not in ELF-format.
Required POV-Ray files:
- POVLINUX.ZIP or POVLINUX.TAR.GZ -- archive containing
an official binary for each of tty-only, SVGALib, and X-Windows
modes. Also contains sample scenes, standard include files, and
documentation.
Recommended:
- Pentium or 486dx or math co-processor for 386 or 486sx
- 8 meg or more RAM.
- SVGA display preferably high color or true color ability.
- If you want display, you'll need either SVGALib or X-Windows.
- Graphic file viewer capable of viewing PPM, GIF, TGA or
PNG formats.
Optional:
The source code is not needed to use POV-Ray. It is provided
for the curious and adventurous.
- POVLIN_S.ZIP - The C source code for POV-Ray for Linux.
Contains generic parts and Linux specific parts. Includes sample
scenes, standard include files, and documentation.
- The GNU C compiler and (optionally) the X include files and
libraries and KNOWLEDGE OF HOW TO USE IT. Although we provide
source code for generic Unix systems, we do not provide technical
support on how to compile the program.
For generic UNIX:
-----------------
Required:
- POVUNIX.ZIP or POVUNIX.TAR.GZ either one alone is sufficient.
These archives contain full generic source, Unix and X-Windows
specific source, sample scenes, standard include files, and
documentation.
- A C compiler for your computer and KNOWLEDGE OF HOW TO USE IT.
Although we provide source code for generic Unix systems, we
do not provide technical support on how to compile the program.
- A text editor capable of editing plain ASCII text files.
Recommended:
- Pentium or 486dx or math co-processor for 386 or 486sx
- 8 meg or more RAM.
- SVGA display preferably high color or true color ability.
- Graphic file viewer capable of viewing PPM, GIF, TGA or
PNG formats.
Optional:
- X Windows if you want to be able to display as you render.
- You will need the X-Windows include files as well. If you're not
familiar with compiling programs for X-Windows you may need some
help from someone who is knowledgeable at your installation because
the X include files and libraries are not always in a standard
place.
----------------------------------------------------------------------------
Each archive includes full documentation for POV-Ray itself as well as
specific instructions for using POV-Ray with your type of computer.
** POV-Ray(tm) is copyrighted freeware written by the POV-Team(tm).
** It may be freely distributed subject to the restrictions
** defined in POVLEGAL.DOC found all of our archives.
** POV-Ray is NOT public domain software.
POV-Ray is based on DKBTrace 2.12 by David K. Buck and Aaron A. Collins.
The POV-Team is a collection of volunteer programmers, designers,
animators and artists meeting via electronic mail on Compuserve's GRAPHDEV
forum. GO GRAPHDEV.
The POV-Team's goal is to create freely distributable, high
quality rendering and animation software written in C that can be easily
ported to many different computers.
If you have any questions about POV-Ray, please contact
Chris Young
[POV-Team Coordinator]
CIS: 76702,1655
Internet: 76702.1655@compuserve.com
---------------------------------------------------------------------------
Where to find the POV-Ray files
---------------------------------------------------------------------------
Graphics Developer Forum on CompuServe
--------------------------------------
POV-Ray headquarters are on CompuServe GRAPHDEV forum ray tracing sections.
We meet there to share info and graphics and discuss ray tracing, fractals
and other kinds of computer art. Everyone is welcome to join in on the
action on CIS GRAPHDEV. Hope to see you there! You can get information
on joining CompuServe by calling (800)848-8990 or visit the CompuServe home
page http://www.compuserve.com. Direct CompuServe access is also available
in Japan, Europe and many other countries.
Internet
--------
The internet home of POV-Ray is http://www.povray.org and ftp.povray.org.
Please stop by often for the latest files, utilities, news and images from
the official POV-Ray internet site.
The comp.graphics.rendering.raytracing newsgroup has many competent POV-Ray
users that are very willing to share their knowledge. They generally ask
that you first browse a few files to see if someone has already answered the
same question, and of course, that you follow proper "netiquette". If you
have any doubts about the qualifications of the folks that frequent the
group, a few minutes spend at the Ray Tracing Competition pages at
www.povray.org will quickly convince you!
PC Graphics area on America On-Line
-----------------------------------
There's an area now on America On-Line dedicated to POV-Ray support and
information. You can find it in the PC Graphics section of AOL. Jump
keyword "PCGRAPHICS". This area includes the Apple Macintosh executables
also. It is best if messages are left in the "Company Support" section.
Currently, Bill Pulver (BPulver) is our representative there.
The Graphics Alternative (TGA) BBS in El Cerrito, CA.
-----------------------------------------------------
For those on the West coast, you may want to find the POV-Ray files on The
Graphics Alternative BBS. It's a great graphics BBS run by Adam Shiffman.
TGA is high quality, active and progressive BBS system which offers both
quality messaging and files to its 1300+ users.
510-524-2780 (PM14400FXSA v.32bis 14.4k, Public)
510-524-2165 (USR DS v.32bis/HST 14.4k, Subscribers)
PCGNet
------
TGA BBS serves as the central hub for a large network of graphics-oriented
BBS systems around the world. Following is a concise listing of active
PCGNet nodes at the time of this writing. The POV-Team can not vouch for
the currency of this information, nor verify that any of these boards may
carry POV-Ray.
USA and Canada
SAUG BBS Bellevue WA 206-644-7115
The Happy Canyon Denver CO 303-759-3598
CHAOS BBS Columbia MO 314-874-2930
411-Exchange Alpharetta GA 404-345-0008
Autodesk Global Village San Rafael CA 415-507-5921
Space Command BBS Kennewick WA 509-735-4894
The Graphics Alternative El Cerrito CA 510-524-2780
The CAD/fx BBS Mesa AZ 602-835-0274
PC-AUG Phoenix AZ 602-952-0638
Time-Out BBS Sadsburyville PA 610-857-2648
John's Graphics Brooklyn Park MN 612-425-4436
CEAO BBS Columbus OH 614-481-3194
Canis Major Nashville TN 615-385-4268
CAD/Engineering Services Hendersonville TN 615-822-2539
The Virtual Dimension Oceanside CA 619-722-0746
Joes CODE BBS West Bloomfield MI 810-855-0894
The Drawing Board BBS Anchorage AK 907-349-5412
The New Graphics BBS Piscataway NJ 908-271-8878
The University Shrewsbury Twp NJ 908-544-8193
Australia
The Baud Room Melbourne VIC 61-3-481-8720
Sydney PCUG Compaq BBS Caringbah NSW 61-2-540-1842
My Computer Company Erskineville NSW 61-2-557-1489
MULTI-CAD Magazine BBS Toowong QLD 61-7-878-2940
Austria
Austrian AutoCAD User Group Graz 43-316-574-426
Belgium
Lucas Visions BBS Boom 32-3-8447-229
Denmark
Horreby SuperBBS Nykoebing Falster 45-53-84-7074
Finland
DH-Online Jari Hiltunen 358-0-40562248
Triplex BBS Helsinki 358-0-5062277
France
CAD Connection Montesson 33-1-39529854
Zyllius BBS! Saint Paul 33-93320505
Germany
Tower of Magic Gelsenkirchen 49-209-780670
Ray BBS Munich Munich 49-89-984723
Netherlands
BBS Bennekom: Fractal Board Bennekom 31-8389-15331
CAD-BBS Nieuwegein 31-3402-90287
Foundation One Baarn 31-2154-22143
New Zealand
The Graphics Connection Wellington 64-4-566-8450
The Graphics Connection II New Plymouth 64-6-757-8092
The Graphics Connection III Auckland 64-9-309-2237
Slovenia
MicroArt Koper 386-66-34986
Sweden
Autodesk On-line Gothenburg 46-31-401718
United Kingdom
Raytech BBS Tain, Scotland 44-1862-83-2020
The Missing Link Surrey, England 44-181-641-8593
CADenza BBS Leicester, UK 44-116-259-6725
Country or long distance dial numbers may require additional numbers
to be used. Consult your local phone company.
POV-Ray Related Books & CD-ROMs
-------------------------------
These items were produced by POV-Team members. Although they are only
current to POV-Ray 2.2 they will still be helpful.
Ray Tracing Creations, 2d Ed.
Chris Young and Drew Wells
ISBN 1-878739-69-7
Waite Group Press 1994
700 pages with color insert and POV-Ray 2.2 on 3.5" MS-Dos disk.
Ray Tracing Worlds with POV-Ray
Alexander Enzmann, Lutz Kretzschmar, Chris Young,
ISBN 1-878739-64-6
Waite Group Press 1994
Includes Moray 1.5x modeler and POV-Ray 2.2 on 3.5" MS-Dos disks.
Ray Tracing for the Macintosh CD
Eduard Schwan
ISBN 1-878739-72-7
Waite Group Press, 1994
Comes with a CD-ROM full of scenes, images, and QuickTime movies,
and an interactive keyword reference. Also a floppy with POV-Ray for
those who don't have a CD ROM drive.
Visit http://www.dnai.com:80/waite/ for more details.
'The Official POV-Ray CDROM'
The Official POV-Ray CDROM is a compilation of images, scene source,
program source, utilities and tips on POV-Ray and 3D graphics from the
Internet and Compuserve. This CD is aimed fairly and squarely at those
who want to create their own images or do general 3D programming work.
It's a good resource for those learning POV-Ray as well as those who are
already proficient, and contains a Microsoft Windows-based interactive
tutorial. The disk is compatible with ISO-9660 and Macintosh formats.
For more details, if you have world wide web access you may visit -
http://www.povray.org/povcd
The CDROM is available for free retrieval and browsing on the World
Wide Web -
http://www.povray.org/pov-cdrom
APPENDIX E Copyright
Persistence of Vision(tm) Ray Tracer
POV-Ray(tm) Version 3.0
Legal Information and License
Draft: February 4, 1996
GENERAL LICENSE AGREEMENT
THIS NOTICE MUST ACCOMPANY ALL OFFICIAL OR CUSTOM PERSISTENCE OF VISION
FILES. IT MAY NOT BE REMOVED OR MODIFIED. THIS INFORMATION PERTAINS TO ALL
USE OF THE PACKAGE WORLDWIDE. THIS DOCUMENT SUPERSEDES ALL PREVIOUS
GENERAL LICENSES OR DISTRIBUTION POLICIES. ANY INDIVIDUALS, COMPANIES OR
GROUPS WHO HAVE BEEN GRANTED SPECIAL LICENSES MAY CONTINUE TO DISTRIBUTE
VERSION 2.x BUT MUST RE-APPLY FOR VERSION 3.0 OR LATER.
This document pertains to the use and distribution of the Persistence of
Vision(tm) Ray Tracer a.k.a POV-Ray(tm). It applies to all POV-Ray program
source files, executable (binary) files, scene files, documentation files,
help file, bitmaps and INI files contained in official POV archives. All
of these are referred to here as "the software".
All of this software is Copyright 1991,1996 by the POV-Ray Development
Team. Although it is distributed as freeware, it is NOT PUBLIC DOMAIN.
The copyrighted package may ONLY be distributed and/or modified according
to the license granted herein. The spirit of the license is to promote
POV-Ray as a standard ray tracer, provide the full POV-Ray package freely
to as many users as possible, prevent POV-Ray users and developers from
being taken advantage of, enhance the life quality of those who come in
contact with POV-Ray. This license was created so these goals could be
realized. You are legally bound to follow these rules, but we hope you
will follow them as a matter of ethics, rather than fear of litigation.
USAGE PROVISIONS
Permission is granted to the user to use the software and associated files
in this package to create and render images. The use of this software for
the purpose of creating images is completely free. The creator of a scene
file and the image created from the scene file, retains all rights to the
image and scene file they created and may use them for any purpose
commercial or noncommercial.
The user is also granted the right to use the scenes files, fonts, bitmaps,
and include files distributed in the INCLUDE, TEXSAMPS and NEWDEMO sub-
directories in their own scenes. Such permission does not extend to files
in the POVSCN sub-directory. POVSCN files are for your enjoyment and
education but may not be the basis of any derivative works.
GENERAL RULES FOR ALL DISTRIBUTION
The permission to distribute this package under certain very specific
conditions is granted in advance, provided that the following conditions
are met.
These archives must not be re-archived using a different method without the
explicit permission of the POV-Team. You may rename the archives only to
meet the file name conventions of your system or to avoid file name
duplications but we ask that you try to keep file names as similar to the
originals as possible. (For example:POVSRC.ZIP to POVSRC30.ZIP)
Ready-to-run unarchived distribution on CD-ROM is also permitted if the
files are arranged in our standard directory or folder structure as though
it had been properly installed on a hard disk.
You must distribute a FULL PACKAGE of files as described in the next
section. No portion of this package may be separated from the package and
distributed separately other than under the conditions specified in the
provisions given below.
Non-commercial distribution in which no money or compensation is charged
(such as a user copying the software for a personal friend or colleague) is
permitted with no other restrictions.
Teachers and educational institutions may also distribute the material to
students and may charge minimal copying costs if the software is to be used
in a course.
DEFINITION OF "FULL PACKAGE"
POV-Ray is contained in two sets of archives for each hardware platform.
1) End user executable archives containing an executable program,
documentation, and sample scenes but no source.
2) Programmer archives containing full source code, documentation,
and sample scenes but no executable.
POV-Ray is officially distributed for MS-Dos; Windows 32-bit; Linux for
Intel '086 series; Apple Macintosh; Apple PowerPC; and Commodore Amiga.
Other systems may be added in the future.
Distributors need not support all platforms but for each platform you
support you must distribute a full package. For example an Macintosh only
BBS need not distribute the Windows versions.
This software may ONLY be bundled with other software packages according to
the conditions specified in the provisions below.
CONDITIONS FOR SHAREWARE/FREEWARE DISTRIBUTION COMPANIES
Shareware and freeware distribution companies may distribute the software
included in software-only compilations using media such as, but not limited
to, floppy disk, CD-ROM, tape backup, optical disks, hard disks, or memory
cards. This section only applies to distributors of collected programs.
Anyone wishing to bundle the package with a shareware product must use the
commercial bundling rules. Any bundling with books, magazines or other
print media should also use the commercial rules.
You must notify us that you are distributing POV-Ray and must provide us
with information on how to contact you should any support issues arise.
No more than five dollars U.S. ($5) can be charged per disk for the copying
of this software and the media it is provided on. Space on each disk must
used as fully as possible. You may not spread the files over more disks
than are necessary.
Distribution on high volume media such as backup tape or CD-ROM is
permitted if the total cost to the user is no more than $0.08 U.S. dollars
per megabyte of data. For example a CD-ROM with 600 meg could cost no more
than $48.00.
CONDITIONS FOR ON-LINE SERVICES AND BBS'S INCLUDING INTERNET
On-line services, BBS's and internet sites may distribute the POV-Ray
software under the conditions in this section. Sites which allow users to
run POV-Ray from remote locations must use separate provisions in the
section below.
The archives must be all be easily available on the service and should be
grouped together in a similar on-line area.
It is strongly requested that sites remove prior versions of POV-Ray to
avoid user confusion and simplify or minimize our support efforts.
The site may only charge standard usage rates for the downloading of this
software. A premium may not be charged for this package. I.E. CompuServe or
America On-Line may make these archives available to their users, but they
may only charge regular usage rates for the time required to download.
ONLINE OR REMOTE EXECUTION OF POV-Ray
Some internet sites have been set up so that remote users can actually run
POV-Ray software on the internet server. Other companies sell CPU time for
running POV-Ray software on workstations or high-speed computers. Such use
of POV-Ray software is permitted under the following conditions.
Fees or charges, if any, for such services must be for connect time,
storage or processor usage ONLY. No premium charges may be assessed for
use of POV-Ray beyond that charged for use of other software. Users must
be clearly notified that they are being charged for use of the computer and
not for use of POV-Ray software.
Users must be prominently informed that they are using POV-Ray software,
that such software is free, and where they can find official POV-Ray
software. Any attempt to obscure the fact that the user is running POV-Ray
expressly prohibited.
All files normally available in a full package distribution, especially a
copy of this license and full documentation must be available for download
or readable online so that users of an online executable have access to all
of the material of a full user package.
If the POV-Ray software has been modified in any way, it must also follow
the provisions for custom versions below.
CONDITIONS FOR DISTRIBUTION OF CUSTOM VERSIONS
The user is granted the privilege to modify and compile the source code for
their own personal use in any fashion they see fit. What you do with the
software in your own home is your business.
If the user wishes to distribute a modified version of the software,
documentation or other parts of the package (here after referred to as a
"custom version") they must follow the provisions given below. This
includes any translation of the documentation into other languages or other
file formats. These license provisions have been established to promote
the growth of POV-Ray and prevent difficulties for users and developers
alike. Please follow them carefully for the benefit of all concerned when
creating a custom version.
No portion of the POV-Ray source code may incorporated into another program
unless it is clearly a custom version of POV-Ray that includes all of the
basic functions of POV-Ray.
All executables, documentation, modified files and descriptions of the same
must clearly identify themselves as a modified and unofficial version of
POV-Ray. Any attempt to obscure the fact that the user is running POV-Ray
or to obscure that this is an unofficial version expressly prohibited.
You must provide all POV-Ray support for all users who use your custom
version. You must provide information so that user may contact you for
support for your custom version. The POV-Ray Development Team is not
obligated to provide you or your users any technical support.
Include contact information in the DISTRIBUTION_MESSAGE macros in the
source file OPTOUT.H and insure that the program prominently displays this
information. Display all copyright notices and credit screens for the
official version.
Custom versions may only be distributed as freeware. You must make all of
your modifications to POV-Ray freely and publicly available with FULL
SOURCE CODE to the modified portions of POV-Ray and must freely distribute
full source to any new parts of the custom version. The goal is that users
must be able to re-compile the program themselves and to be able to further
improve the program with their own modifications.
You must provide documentation for any and all modifications that you have
made to the program that you are distributing. Include clear and obvious
information on how to obtain the official POV-Ray.
The user is encouraged to send enhancements and bug fixes to the POV-Ray
Development Team, but the team is in no way required to utilize these
enhancements or fixes. By sending material to the team, the contributor
asserts that he owns the materials or has the right to distribute these
materials. He authorizes the team to use the materials any way they like.
The contributor still retains rights to the donated material, but by
donating, grants unrestricted, irrevocable usage and distribution rights to
the POV-Ray Development Team. The team doesn't have to use the material,
but if we do, you do not acquire any rights related to POV-Ray. The team
will give you credit as the creator of new code if applicable.
Include a copy of this document.
CONDITIONS FOR COMMERCIAL BUNDLING
Vendors wishing to bundle POV-Ray with commercial software (including
shareware) or with publications must first obtain explicit permission from
the POV-Ray Development Team. This includes any commercial software or
publications, such as, but not limited to, magazines, cover-disk
distribution, books, newspapers, or newsletters in print or machine
readable form.
The POV-Ray Development Team will decide if such distribution will be
allowed on a case-by-case basis and may impose certain restrictions as it
sees fit. The minimum terms are given below. Other conditions may be
imposed.
Purchasers of your product must not be led to believe that they are
paying for POV-Ray. Any mention of the POV-Ray bundle on the box, in
advertising or in instruction manuals must be clearly marked with a
disclaimer that POV-Ray is free software and can be obtained for free or
nominal cost from various sources.
Include clear and obvious information on how to obtain the official
POV-Ray.
You must provide all POV-Ray support for all users who acquired POV-
Ray through your product. The POV-Ray Development Team is not obligated to
provide you or your customers any technical support.
Include a credit page or pages in your documentation for POV-Ray.
If you modify any portion POV-Ray for use with your hardware or
software, you must follow the custom version rules in addition to these
rules.
Include contact and support information for your product.
Include a full user package as described above.
OTHER PROVISIONS
The team permits and encourages the creation of programs, including
commercial packages, which import, export or translate files in the POV-Ray
Scene Description Language. There are no restrictions on use of the
language itself. We reserve the right to add or remove or change any part
of the language.
"POV-Ray", "Persistence of Vision", and "POV-Help" are trademarks of the
POV-Ray Development Team.
While we do not claim any restrictions on the letters "POV" alone, we
humbly request that you not use POV in the name of your product. Such use
tends to imply it is a product of the POV-Ray Development Team. Existing
programs which used "POV" prior to the publication of this document need
not feel guilty for doing so provided that you make it clear that the
program is not the work of the team nor endorsed by us.
REVOCATION OF LICENSE
VIOLATION OF THIS LICENSE IS A VIOLATION OF COPYRIGHT LAWS. IT WILL RESULT
IN REVOCATION OF ALL DISTRIBUTION PRIVILEGES AND MAY RESULT IN CIVIL OR
CRIMINAL PENALTY.
Such violators who are prohibited from distribution will be identified in
this document.
In this regard, "PC Format", a magazine published by Future Publishing,
Ltd. in the United Kingdom, distributed incomplete versions of POV-Ray 1.0
in violation the license which was effect at the time. They later
attempted to distribute POV-Ray 2.2 without prior permission of the POV-Ray
Team in violation the license which was in effect at the time. Therefore
"PC Format", and any other magazine, book or CD-ROM publication owned by
Future Publishing is expressly prohibited from any distribution of POV-Ray
software until further notice.
DISCLAIMER
This software is provided as is without any guarantees or warranty.
Although the authors have attempted to find and correct any bugs in the
package, they are not responsible for any damage or losses of any kind
caused by the use or misuse of the package. The authors are under no
obligation to provide service, corrections, or upgrades to this package.
---End of License Information---
We sincerely hope you have fun with our program. If you have any problems
with the program, the team would like to hear about them. Also, if you have
any comments, questions or enhancements, please contact the POV-Ray Team on
the CompuServe Information Service in the GO GRAPHICS forums, GRAPHDEV
forum. Also check us out on the internet at http://www.povray.org or
ftp.povray.org.
License enquiries should be made via email and limited technical support is
available via email to:
Chris Young
POV-Ray Team Coordinator
CIS: 76702,1655
Internet 76702.1655@compuserve.com
The following postal address is only for official license business and only
if email is impossible.
We do not provide technical support via regular mail, only email. We don't
care if you don't have a modem or online access. We will not mail you
disks with updated versions. Do not send money.
Chris Young
3119 Cossell Drive
Indianapolis, IN 46224 U.S.A.
The other authors' contact information may be found in the documentation.
APPENDIX F Authors
Steve Anger
(POV-Ray 2.0/3.0 developer)
CIS: 70714,3113
Internet: sanger@hookup.net
Randy Antler
(IBM-PC display code enhancements)
John Baily
(RLE targa code)
Eric Barish
(Ground fog code)
Dieter Bayer
(POV-Ray 3.0 developer)
CIS: 100255,3074
Kendall Bennet
(PMODE library support)
Steve Bennett
(GIF support)
Jeff Bowermaster
(Beta test)
David Buck
(Original author of DKBTrace)
(POV-Ray 1.0 developer)
Chris Cason
(POV-Ray 2.0/3.0 developer, POV-Help, Windows port)
Internet (preferred): Chris.Cason@oaks.com.au or Chris.Cason@povray.org
CIS: 100032,1644
Aaron Collins
(Co-author of DKBTrace 2.12)
(POV-Ray 1.0 developer)
Chris Dailey
(POV-Ray 3.0 developer)
CIS:
Steve Demlow
(POV-Ray 3.0 developer)
CIS:
Joris van Drunen Littel
(Mac beta tester)
Alexander Enzmann
(POV-Ray 1.0/2.0/3.0 developer)
CIS: 70323,2461
Internet: xander@mitre.com
Dan Farmer
(POV-Ray 1.0/2.0/3.0 developer)
CIS: 74431,1075
David Harr
(Mac balloon help and palette code)
Jimmy Hoeks
(Help file for Windows user interface)
Terry Kanakis
(Camera fix)
Kari Juharvi Kivisalo
(Ground fog code)
Adam Knight
(Mac beta tester, Mac Apple Guide developer)
CIS:
Lutz Kretzschmar
(IBM-PC display code [SS24 truecolor], part of the anti-aliasing code)
CIS: 100023,2006
Charles Marslette
(IBM-PC display code)
Pascal Massimino
(Fractal objects)
Jim McElhiney
(POV-Ray 3.0 developer)
CIS:
Mike Miller
(Artist, scene files, stones.inc)
CIS: 70353,100
Douglas Muir
(Bump maps, height fields)
Joel NewKirk
(Amiga Version)
CIS:
Jim Nitchals
(Mac version, scene files)
Paul Novak
(Texture contributions)
Dave Park
(Amiga support, AGA video code)
David Payne
(RLE targa code)
Bill Pulver
(Time code, IBM-PC compile)
Anton Raves
(Beta tester, helping out on several Mac thingies)
CIS: 100022,2603
Dan Richardson
(Docs)
CIS:
Tim Rowley
(PPM and Windows-specific BMP image format support)
Internet: trowley@geom.umn.edu
Robert Schadewald
(Beta tester)
CIS:
Eduard Schwan
(Mac version, mosaic preview, docs)
CIS: 71513,2161
Robert Skinner
(Noise functions)
Erkki Sondergaard
(Scene files)
CIS:
Zsolt Szalavari
(Halo code)
Internet: zsolt@cg.tuwien.ac.at
Scott Taylor
(Leopard and onion textures)
Timothy Wegner
(Fractal objects)
CIS:
Drew Wells
(POV-Ray 1.0 developer, POV-Ray 1.0 team coordinator)
Chris Young
(POV-Ray 1.0/2.0/3.0 developer, POV-Ray 2.0/3.0 team coordinator)
CIS: 76702,1655
